Долгое время моей IDE была PhpStorm. Для JavaScript я опирался на JSDoc как на язык контрактов: сигнатуры, навигация, автодополнение. Всё работало стабильно, предсказуемо и привычно. Но переход в Visual Studio Code оказался неожиданно болезненным. Анализ JavaScript-кода стал менее устойчивым. Предупреждения и сообщения формулируются в терминах TypeScript, который я не использую по "религиозным соображениям". JSDoc присутствует, но в инфраструктурном и библиотечном коде его влияние практически исчезает.

Ключевой факт, который это объясняет: JavaScript в VSCode анализируется как проекция TypeScript-модели через tsserver. Первый практический сигнал - jsconfig.json. Без него JavaScript анализируется фрагментарно:

{
  "compilerOptions": {
    "checkJs": true
  }
}

После добавления файла проект начинает восприниматься как целостный: появляются связи между файлами, навигация, типовые подсказки. Сам JS-код при этом не меняется. Этот файл не участвует в выполнении и не относится к стандарту JavaScript. Он нужен только анализатору VSCode, в PhpStorm я прекрасно обходился без него.

Но VSCode код сам не анализирует. Все подсказки и навигация приходят от tsserver. Связь с ним осуществляется через LSP. Поведение IDE полностью определяется возможностями выбранного language server’а. Для JavaScript в реальной практике используется только tsserver; JS-first или JSDoc-first альтернатив для анализатора нет (нет, Microsoft не делал и не собирается делать подобрных альтернатив).

tsserver строит модель проекта на основе статических импортов в границах, заданных jsconfig.json. Всё, что определяется динамически или формируется на этапе выполнения, в эту модель не попадает.

Я хорошо ощущаю это в собственных проектах. В их архитектуре используется позднее связывание и внедрение зависимостей через конструктор, реализованное в моей библиотеке @teqfw/di. Статические импорты сведены к минимуму - фактически только для загрузки самой DI-библиотеки. Всё дальнейшее связывание происходит динамически и остаётся за пределами возможностей анализа tsserver.

На уровне библиотек ограничения анализа преодолеваются через механизм публичных контрактов. При анализе внешнего проекта VSCode опирается не на JavaScript-код npm-зависимости, а на файл деклараций, указанный в package.json в поле types. Именно этот файл используется tsserver для построения типовой модели зависимости. Реализация библиотеки и JSDoc-аннотации внутри node_modules в анализ потребляющего проекта не включаются.

JSDoc в этой схеме работает только в той мере, в какой его можно однозначно свести к типовой проекции. Семантические и поведенческие аспекты в модель типов не попадают.

В итоге в VSCode нет отдельного режима анализа "чистого JavaScript". Существует единая TypeScript-ориентированная модель, и JavaScript анализируется ровно настолько, насколько его форма допускает такую проекцию.

Это границы инструмента (VSCode). Когда их принимаешь, поведение IDE становится чуть более предсказуемым и понятным.

P.S.

Данная публикация является "выжимкой" (конспектом) более полного изложения этой же информации и сделана специально для Хабра в рамках изучения принципа первичного принятия знания (это моя формулировка, можете даже не гуглить). Если вам уже знакомо всё, что я "выжал", или просто не интересно - считайте, что сэкономили время, не ознакомившись с полным изложением. Если хотите что-либо обсудить - welcome в комменты прямо тут.

P.P.S.

И этот конспект, и полное изложение делались с применением LLM. Если вас такое на Хабре не устраивает и вы хотите поставить статье "минус", большая просьба - поставьте на меня фильтр в своей ленте, чтобы я вам больше не попадался и не раздражал. Ищите вот этот вот функционал в правом углу сразу под публикацией: