Инструменты статического анализа TypeScript: полное руководство для команд разработчиков.

Система типов TypeScript выявляет ряд существенных ошибок до выполнения кода: несоответствия типов, отсутствующие свойства, некорректные сигнатуры функций. Однако она не может обнаружить всё остальное: уязвимости безопасности, зависящие от способа передачи данных в приложении, архитектурные нарушения, накапливающиеся со временем по мере размывания границ между командами, неработающие экспортируемые объекты, остающиеся в кодовой базе ещё долго после удаления вызывающих их функций, и ошибки асинхронного программирования, которые компилируются правильно, но приводят к сбою при определённых условиях выполнения. Инструменты статического анализа заполняют эти пробелы, и выбор правильной комбинации зависит от того, что именно вы пытаетесь обнаружить.

В этом руководстве рассматриваются инструменты, важные для команд, работающих с TypeScript в 2026 году: слой линтинга (ESLint с typescript-eslint, Biome, OxcLint), слой безопасности (Semgrep, Snyk Code, SonarQube), архитектурный слой (Dependency-Cruiser, Deptrac, Nx), слой мертвого кода (Knip) и слой глубокого анализа (ts-morph, сам компилятор TypeScript). Для каждого инструмента основное внимание уделяется его функционалу, способу настройки и тому, когда он не подходит для решения конкретной задачи.

Сравнительная таблица инструментов статического анализа TypeScript

Прежде чем перейти к рассмотрению отдельных инструментов, в таблице ниже приведено соответствие каждого инструмента его основной функции, пригодности для CI и идеальному сценарию использования. Ни один инструмент не охватывает все аспекты; для эффективного анализа качества TypeScript требуется использовать несколько инструментов одновременно.

Инструмент	Основная функция	Подходит для КИ	Стоимость	Для каких задач
ESLint + typescript-eslint	Проверка синтаксиса, стиль, правила, учитывающие тип данных	Да	Бесплатно	Общекомандные соглашения, асинхронная типобезопасность
биом	Проверка синтаксиса + форматирование	Да	Бесплатно	Замена ESLint + Prettier, скорость
OxcLint	Проверка синтаксиса (совместима с ESLint)	Да	Бесплатно	Монорепозитории, требующие быстрой проверки синтаксиса.
Компилятор TypeScript (tsc)	Проверка типа	Да	Бесплатно	Ошибки ввода, принудительное включение строгого режима
Семгреп	SAST, пользовательские шаблоны	Да	Бесплатно + платно	Сканирование безопасности, пользовательские правила организации
Код Сныка	SAST, безопасность зависимостей	Да	Бесплатно + платно	Команды, ориентированные на безопасность, интеграция с IDE.
SonarQube / SonarCloud	Контроль качества, отслеживание тенденций	Да	Бесплатно + платно	Панели мониторинга качества предприятия
СонарЛинт	Обратная связь о качестве на уровне IDE	только IDE	Бесплатно	Встроенные подсказки по безопасности и качеству
Dependency-Cruiser	Обеспечение соблюдения графа зависимостей	Да	Бесплатно	Проверка архитектурных правил
Дептрак	Контроль границ слоев	Да	Бесплатно	Чистая архитектура, границы DDD
Nx	Управление зависимостями монорепо	Да	Бесплатно + платно	Границы модулей монорепозитория
резать	Мертвый код и неиспользуемые экспорты	Да	Бесплатно	Сокращение неиспользуемого кода в масштабах предприятия
ts-морф	Программный анализ TS AST	Выборочный запуск	Бесплатно	Пользовательский анализ, модификации кода, инструменты

Слой 1: Проверка синтаксиса и стиль

ESLint с typescript-eslint

ESLint остается основой проверки синтаксиса TypeScript. С учетом typescript-eslint Этот пакет предоставляет доступ к информации о типах TypeScript и позволяет применять правила, требующие контекста типов, наиболее ценными из которых являются правила, специфичные для асинхронных операций, которые выявляют распространенные ошибки, связанные с промисами.

колотить

npm install --save-dev typescript-eslint

Javascript

// eslint.config.js
import tseslint from "typescript-eslint";

export default tseslint.config(
  ...tseslint.configs.strictTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
    rules: {
      // Async safety rules -- highest value TypeScript-specific rules
      "@typescript-eslint/no-floating-promises": "error",
      "@typescript-eslint/await-thenable": "error",
      "@typescript-eslint/no-misused-promises": "error",
      "@typescript-eslint/require-await": "warn",
      // Type safety
      "@typescript-eslint/no-explicit-any": "warn",
      "@typescript-eslint/no-unsafe-assignment": "error",
      "@typescript-eslint/no-unsafe-return": "error",
    },
  }
);

Четыре приведенных выше правила асинхронного выполнения — это наиболее ценное дополнение, которое typescript-eslint предоставляет по сравнению с обычным ESLint. Они отлавливают: необработанные промисы (плавающие промисы), await применяется к значениям, не являющимся промисами, к промисам, передаваемым в колбэки, ожидающим синхронные функции, и к асинхронным функциям, которые никогда не используют промисы. awaitЭто шаблоны, которые компилируются без ошибок, но приводят к сбоям во время выполнения при определенных условиях.

Что ESLint не может сделать : анализ потока данных между файлами, обеспечение соблюдения архитектурных границ, отслеживание уязвимостей безопасности или обнаружение неработающих экспортов. Для этого требуются другие уровни, описанные ниже.

Biome: Современная замена ESLint + Prettier

Biome заменяет ESLint и Prettier одним исполняемым файлом на Rust, работающим в 25-35 раз быстрее. Он поддерживает JavaScript, TypeScript, JSX и JSON. Для новых проектов или команд, недовольных сложностью плагинов ESLint и низкой производительностью в больших кодовых базах, Biome является самой мощной современной альтернативой.

колотить

npm install --save-dev --save-exact @biomejs/biome
npx @biomejs/biome init

колотить

# Check and format in one pass
npx @biomejs/biome check --write src/

# CI mode -- no modifications, exit non-zero on any finding
npx @biomejs/biome ci src/

Экосистема плагинов Biome меньше, чем у ESLint, что важно для команд, использующих множество пользовательских правил или плагинов, специфичных для конкретного фреймворка. Для команд, использующих только основные правила ESLint и форматирование Prettier, Biome обеспечивает эквивалентное покрытие при значительно меньшем времени выполнения.

OxcLint: Быстрая совместимость с ESLint

OxcLint (часть проекта Oxc) выполняет правила, совместимые с ESLint, в 50-100 раз быстрее. Он не заменяет всю экосистему ESLint, но служит самым быстрым вариантом для конвейеров CI, где время проверки является узким местом.

колотить

npm install --save-dev oxlint
npx oxlint src/

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

Уровень 2: Проверка типов, компилятор TypeScript

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

JSON

{
  "compilerOptions": {
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true,
    "useUnknownInCatchVariables": true
  }
}

колотить

# Type-check only, no emit -- ideal for CI
npx tsc --noEmit

noUnusedLocals и noUnusedParameters На уровне компилятора перехватываются неиспользуемые переменные и параметры функций. useUnknownInCatchVariables (TypeScript 4.4+) типы перехватывают исключения, поскольку unknown , а не any, что приводит к необходимости явного сужения типа перед использованием.

Анализ потока управления в TypeScript Это встроенная функция компилятора, позволяющая сужать типы внутри условных ветвлений. Это не отдельный инструмент, позволяющий strict Этот режим гарантирует его строгое применение. Анализ потока управления компилятора понимает проверки типов. typeof чеки, instanceofи дискриминировали модели профсоюзного движения.

Ограничение tsc : компилятор TypeScript не обнаруживает уязвимости безопасности, нарушения архитектурных границ или неработающие экспортируемые объекты. Он обнаруживает ошибки типов, и делает это однозначно.

Уровень 3: Безопасность, SAST для TypeScript

Semgrep: сканирование безопасности на основе шаблонов

Semgrep обнаруживает уязвимости безопасности с помощью сопоставления с шаблонами кода. В случае TypeScript он может обнаруживать SQL-инъекции, XSS, жестко закодированные учетные данные и небезопасные методы. eval Использование, загрязнение прототипов и небезопасные конфигурации Express.js — шаблоны, которые компилируются корректно, но создают уязвимости, которые можно использовать для злоупотреблений.

YAML

# Custom rule: flag user input in SQL queries (TypeScript)
rules:
  - id: ts-sql-injection-risk
    patterns:
      - pattern: |
          const query = `SELECT ... ${$USER_INPUT} ...`;
    message: "User input directly interpolated into SQL -- use parameterized queries"
    languages: [typescript]
    severity: ERROR

колотить

# Run with the community TypeScript security rules
semgrep scan --config=p/typescript --config=p/owasp-top-ten src/

Semgrep дополняет ESLint, а не конкурирует с ним. ESLint обеспечивает соблюдение соглашений; Semgrep выявляет антипаттерны безопасности. Большинству команд разработчиков TypeScript, заботящихся о безопасности, следует использовать оба инструмента.

Snyk Code: SAST на основе машинного обучения с интеграцией с IDE.

Snyk Code выполняет SAST (системное статистическое тестирование) с помощью механизма анализа на основе машинного обучения, который отслеживает потоки заражения файлов. Он интегрируется в VS Code и IDE JetBrains, отображая результаты непосредственно во время написания кода, вместо того чтобы ждать запуска CI (непрерывной интеграции).

колотить

npm install --save-dev snyk
npx snyk auth
npx snyk code test

Ориентация Snyk Code на удобство для разработчиков, встроенная обратная связь от IDE, предложения по исправлению ошибок рядом с каждым обнаруженным недостатком и примеры устранения проблем делают его лучшим выбором, когда обучение основам безопасности так же важно, как и обнаружение угроз.

SonarQube и SonarLint: контрольные точки качества и отслеживание трендов.

SonarQube обеспечивает непрерывный анализ качества кода с помощью панели мониторинга, отслеживания тенденций и оформления запросов на слияние. Для TypeScript он обнаруживает ошибки, «запахи кода», уязвимости безопасности и дублирование кода. SonarLint — это расширение IDE, которое отображает правила SonarQube локально.

Для команд, работающих с TypeScript, SonarCloud (облачная версия) — более простой вариант: бесплатно для общедоступных репозиториев, с интеграцией CI через GitHub Actions или GitLab CI за считанные минуты.

YAML

# .github/workflows/sonar.yml
- name: SonarCloud Scan
  uses: SonarSource/sonarcloud-github-action@master
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

Главное преимущество SonarQube перед обычной проверкой кода заключается в его модели анализа тенденций: как меняется качество кода с течением времени, какие компоненты ухудшаются и каков рейтинг качества нового кода для каждого запроса на слияние. Эти показатели, доступные руководству, — это то, чего не могут обеспечить ESLint и Semgrep.

Уровень 4: Архитектурный анализ

Dependency-Cruiser: Обеспечение соблюдения правил границ модулей

Dependency-Cruiser проверяет, соответствует ли ваш граф импорта определенным архитектурным правилам. Он генерирует визуальные графы зависимостей и завершает работу CI с ошибкой, если код нарушает ограничения границ модулей.

Javascript

// .dependency-cruiser.cjs
module.exports = {
  forbidden: [
    {
      name: "no-circular",
      severity: "error",
      comment: "Circular dependencies make code hard to test and maintain",
      from: {},
      to: { circular: true },
    },
    {
      name: "no-ui-in-domain",
      severity: "error",
      comment: "Domain modules must not import from UI layer",
      from: { path: "^src/domain" },
      to: { path: "^src/ui" },
    },
    {
      name: "no-external-in-shared",
      severity: "warn",
      comment: "Shared utilities should minimize external dependencies",
      from: { path: "^src/shared" },
      to: { pathNot: "^(src|node_modules/(lodash|date-fns))" },
    },
  ],
};

колотить

npx depcruise --validate .dependency-cruiser.cjs src/

Dependency-Cruiser напрямую отвечает на запросы «инструмент анализа зависимостей React» в данных Search Console; это стандартный инструмент для генерации и проверки графов зависимостей в проектах на TypeScript/React.

Deptrac: Послойное обеспечение соблюдения границ

Deptrac обеспечивает соблюдение архитектурных уровней, гарантируя, что код, отвечающий за сохранение данных, не может импортировать данные из представления, что доменные объекты не зависят от инфраструктуры, и что границы модулей соблюдаются во всей кодовой базе.

YAML

# deptrac.yaml
parameters:
  layers:
    - name: Domain
      collectors:
        - type: directory
          value: src/domain
    - name: Application
      collectors:
        - type: directory
          value: src/application
    - name: Infrastructure
      collectors:
        - type: directory
          value: src/infrastructure
  ruleset:
    Domain:
      - ~Infrastructure  # Domain must not depend on Infrastructure
    Application:
      - Domain
    Infrastructure:
      - Application
      - Domain

Deptrac наиболее полезен в проектах, реализуемых по шаблонам «Чистая архитектура», «DDD» или «Гексагональная архитектура», где изоляция слоев является ограничением проектирования, а не просто предпочтением.

Nx: Управление зависимостями на уровне монорепозитория

Для монорепозиториев TypeScript Nx обеспечивает контроль границ модулей, обнаружение затронутых сборок и визуализацию графа зависимостей для всех проектов в репозитории.

JSON

// .eslintrc.json -- Nx module boundary rules
{
  "rules": {
    "@nx/enforce-module-boundaries": [
      "error",
      {
        "allow": [],
        "depConstraints": [
          { "sourceTag": "scope:shared", "onlyDependOnLibsWithTags": ["scope:shared"] },
          { "sourceTag": "scope:feature", "onlyDependOnLibsWithTags": ["scope:shared", "scope:feature"] },
          { "sourceTag": "scope:app", "onlyDependOnLibsWithTags": ["scope:shared", "scope:feature"] }
        ]
      }
    ]
  }
}

Nx affected Эти команды запускают только те тесты и проверку синтаксиса, которые относятся к измененным модулям, что значительно сокращает время непрерывной интеграции в больших монорепозиториях.

Уровень 5: Обнаружение мертвого кода

Knip: поиск неиспользуемых экспортируемых файлов, зависимостей и других зависимостей.

Knip анализирует весь граф модулей для выявления неиспользуемых экспортов, неиспользуемых файлов и неиспользуемых ресурсов. package.json зависимости, класс накопления кода, который использует ESLint. no-unused-vars Не удается перехватить, потому что поиск осуществляется только внутри файла.

колотить

npm install --save-dev knip
npx knip

JSON

// knip.json
{
  "entry": ["src/index.ts", "src/**/*.test.ts"],
  "project": ["src/**/*.ts"],
  "ignore": ["src/generated/**"],
  "ignoreDependencies": ["vitest"]
}

Поиск Knip в данных SC осуществляется напрямую по запросу «обнаружение мертвого кода, неиспользуемые экспорты, JavaScript, TypeScript». Это наиболее эффективный на сегодняшний день инструмент для идентификации мертвого кода на уровне модулей в проектах TypeScript.

Уровень 6: Программный анализ, ts-morph

ts-morph — это обертка для API компилятора TypeScript, которая упрощает написание пользовательского анализа, модификаций кода и инструментов для работы с AST TypeScript. Поиск осуществляется непосредственно в данных SC по запросам «ts-morph» и «ts morph».

машинопись

import { Project } from "ts-morph";

const project = new Project({ tsConfigFilePath: "tsconfig.json" });

// Find all async functions that never await anything
const suspiciousAsyncFns: string[] = [];

for (const sourceFile of project.getSourceFiles()) {
  for (const fn of sourceFile.getFunctions()) {
    if (fn.isAsync()) {
      const hasAwait = fn.getDescendantsOfKind(
        SyntaxKind.AwaitExpression
      ).length > 0;
      if (!hasAwait) {
        suspiciousAsyncFns.push(
          `${sourceFile.getFilePath()}:${fn.getName() ?? "anonymous"}`
        );
      }
    }
  }
}

console.log("Async functions with no await:", suspiciousAsyncFns);

ts-morph — это не готовый к использованию инструмент анализа, а библиотека, которую вы используете для его создания. Она подходит для команд, которым требуется индивидуальный анализ, выходящий за рамки возможностей существующих инструментов: скрипты миграции, пользовательские архитектурные валидаторы, автоматизированный рефакторинг или конвейеры генерации кода.

Анализ статических процессов TypeScript Async/Await

Данные Search Console показывают определенную группу запросов, связанных с «инструментом для статического анализа TypeScript с использованием async await» и «инструментом для анализа уязвимостей в TypeScript с использованием async await». Эти запросы отражают стремление специалистов найти инструменты, которые позволяют анализировать ошибки асинхронного программирования на уровне типов.

Практическое решение для команд, работающих с TypeScript в продакшене, — это четыре правила typescript-eslint, специфичные для асинхронных операций (no-floating-promises, await-thenable, no-misused-promises, require-await) в сочетании с strictNullChecks и useUnknownInCatchVariablesВместе они позволяют выявлять наиболее распространенные ошибки асинхронных типов без необходимости использования инструментов академических исследований.

Для команд, занимающихся исследованиями безопасности, связанными с уязвимостями асинхронного выполнения, TAJS и Jelly — это академические статические анализаторы, моделирующие семантику асинхронного выполнения JavaScript, но они являются исследовательскими инструментами, а не инструментами для разработки в производственной среде.

Angular и React: статический анализ, специфичный для каждого фреймворка.

Для команд, работающих с Angular, @angular-eslint Предоставляет специфические для Angular правила линтинга, охватывающие шаблоны компонентов, анализ шаблонов и внедрение сервисов. Интегрируется с конфигурацией ESLint + typescript-eslint, описанной выше.

Для команд, работающих с React, eslint-plugin-react, eslint-plugin-react-hooks и eslint-plugin-jsx-a11y Плагины охватывают специфические для React шаблоны. Dependency-Cruiser обрабатывает специфический для React анализ графа зависимостей и является инструментом, лежащим в основе запросов «инструмент командной строки анализа зависимостей React» в данных SC.

Интеграция с IDE: инструменты для VS Code и JetBrains

Запросы «лучшие инструменты для проверки качества кода, интегрируемые с VS Code» и «лучшие инструменты для проверки качества кода, интегрируемые с IDE» отражают реальную потребность: обратная связь от CI поступает слишком поздно, чтобы изменить поведение. Анализ, интегрированный с IDE, обеспечивает наиболее эффективную обратную связь.

VS Code : расширение ESLint с проверкой совместимости с rust-analyzer Clippy, расширение SonarLint для встроенных правил SonarQube, расширение Snyk для анализа уязвимостей безопасности и встроенная служба языка TypeScript для обратной связи на уровне типов.

JetBrains (WebStorm/IntelliJ) : WebStorm поставляется со встроенной поддержкой TypeScript, которая отображает ошибки типов непосредственно в коде, а также интегрируется с ESLint, Prettier и SonarLint. Встроенная система проверки охватывает многие из тех же шаблонов, что и правила ESLint.

Настройка VS Code для максимального охвата статического анализа TypeScript :

JSON

// .vscode/settings.json
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": ["javascript", "typescript", "typescriptreact"],
  "sonarlint.connectedMode.project": {
    "connectionId": "my-sonarcloud",
    "projectKey": "my-org_my-project"
  }
}

Как SMART TS XL Расширяет возможности анализа TypeScript на всю организацию.

Описанные выше инструменты позволяют работать с TypeScript в рамках проекта на TypeScript. В организациях, где сервисы TypeScript взаимодействуют с пакетными программами COBOL, API Java, конвейерами обработки данных Python или устаревшими мэйнфреймными системами, инструменты, работающие с одним языком, не могут увидеть зависимости, выходящие за рамки одного языка.

SMART TS XLАвтора статический анализ кода Рассматривается TypeScript наряду со всеми другими языками программирования в корпоративной среде: COBOL, JCL, Java, Python, RPG, SQL, и строится единая модель зависимостей для всех них. Когда сервис на TypeScript вызывает API, который поддерживается программой на COBOL, SMART TS XL можно проследить эту взаимосвязь и включить ее в анализ воздействия прежде чем вносить какие-либо изменения в любой из компонентов.

Функция корпоративного поиска позволяет запрашивать всю многоязычную кодовую базу: за считанные секунды можно найти каждый импорт TypeScript конкретного модуля, каждый метод Java, вызываемый сервисом TypeScript, каждый COBOL-кодбук, передающий данные в API, используемый TypeScript, по миллионам строк кода на любом сочетании языков.

Для корпоративных команд, использующих TypeScript как один из языков в более широком портфолио, SMART TS XL обеспечивает архитектурную наглядность и межъязыковое взаимодействие. отображение зависимостей Это заставляет инструменты, специфичные для TypeScript, рассматривать только свою часть системы, в то время как SMART TS XL видит целое.

Создание правильного стека технологий

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

Минимально необходимый набор инструментов (для нового проекта и небольшой команды):

• строгий режим TypeScript
• ESLint с асинхронными правилами typescript-eslint
• npm audit для уязвимостей зависимостей

Производственный стек приложений (средняя команда, уделяющая особое внимание безопасности):

• Все выше, плюс:
• Для форматирования используйте Biome или Prettier.
• Semigrep для обеспечения безопасности SAST
• Обрезать для мертвого кода
• SonarCloud для качественного анализа тенденций.

Корпоративный стек / монорепозиторий (большая команда, архитектурные ограничения):

• Все выше, плюс:
• Dependency-Cruiser для обеспечения соблюдения границ модулей.
• Nx для оптимизации сборки, затронутой монорепозиторием
• Deptrac для проверки границ слоев
• SonarQube (самостоятельное размещение) для проведения проверок качества на локальных серверах.

Многоязычный корпоративный стек (TypeScript наряду с устаревшими системами):

• Все выше, плюс:
• SMART TS XL для анализа влияния языков и сопоставления зависимостей