Инструменты разработчика · JSON форматировщик и валидатор
Исправьте сломанный package.json до того, как это сделает CI: чтение позиции ошибки
· Почему это важно
JSON рабочий процесс разработчика проверка
Отредактированные вручную package.json, composer.json или launch.json терпят неудачу спустя долгое время после того, как вы их сохранили, обычно в CI. В этом посте показано, как выполнить проверку перед коммитом и быстро прочитать позицию ошибки.
Двенадцать минут конвейера, чтобы узнать об одной запятой
Двенадцать минут конвейера, чтобы узнать об одной запятой — конфликте слияния, разрешенном вручную, зеленом редакторе и красной сборке. Проверка репозитория может выглядеть нормально, потому что Git записывает байты, а не анализирует ли манифест. Затем CI устанавливает зависимости, достигает поврежденного файла и останавливается до того, как тесты дадут какой-либо полезный сигнал.
Инструмент проверяет только строгий синтаксис JSON и принимает документы длиной до 8,000,000 JavaScript символов. package.json и composer.json являются подходящими строгими примерами. Такие файлы, как tsconfig.json, могут использовать анализатор, устойчивый к комментариям, поэтому отклонение их комментариев как JSON не доказывает, что инструмент-владелец их отклонит. Проверьте соответствие грамматики, которую фактически декларирует потребляющая программа.
Какие конфигурационные файлы JSON ломаются чаще всего
Какие конфигурационные файлы JSON ломаются чаще всего — package.json, composer.json, launch.json и файлы блокировки, и почему tsconfig.json, допускающий комментарии, требует отдельного ухода. Манифесты, отредактированные человеком, имеют тенденцию давать сбой из-за блоков зависимостей, сценариев и настроек вложенных инструментов. Сгенерированные файлы блокировки терпят неудачу по-разному: разрешение конфликтов вручную может привести к повреждению разделителей или дублированию структурных разделов.
Не думайте, что каждый файл с расширением типа JSON использует строгий JSON. Настройки VS Code и конфигурация TypeScript обычно разрешают комментарии или конечные запятые через специализированные анализаторы, тогда как манифесты пакетов обычно этого не делают. По возможности проверяйте сгенерированный файл блокировки с помощью его менеджера пакетов, поскольку сам по себе действительный синтаксис не может восстановить хэши, правила упорядочивания или внутреннюю согласованность, ожидаемую этим генератором.
Почему инструменты поздно выходят из строя: менеджеры пакетов и компиляторы выполняют синтаксический анализ по требованию, поэтому синтаксическая ошибка возникает во время установки или сборки, а не при сохранении.
Почему инструменты поздно выходят из строя — менеджеры пакетов и компиляторы выполняют синтаксический анализ по требованию, поэтому синтаксическая ошибка возникает во время установки или сборки, а не при сохранении. Текстовый редактор может раскрашивать фигурные скобки без запуска авторитетного анализатора, а измененный манифест может не быть прочитан во время узкой локальной задачи. CI запускается из чистой среды и проверяет пути установки, которые пропускают кэшированные рабочие станции.
Результирующая задержка включает в себя время ожидания, оформление заказа, настройку зависимостей и несвязанные предварительные задания. Хуже того, в конечном сообщении может быть указан только недопустимый файл пакета, а исходная строка скрыта за выводом команды. Локальный анализ сразу после редактирования разрушает этот цикл обратной связи. Он также отделяет грамматическую ошибку от последующих ошибок разрешения зависимостей или схемы, которые требуют другого исследования.
Чтение положения ошибки под давлением
Чтение позиции ошибки под давлением — строка и столбец, предыдущий токен и три шаблона конфликта слияния, которые создают недопустимый JSON. Отмеченный персонаж — это место, где продолжение стало невозможным, и не всегда там, где началась ошибка. Заключительная кавычка может раскрыть более раннюю неэкранированную кавычку; скобка может показать отсутствующую запятую непосредственно перед следующим свойством.
После слияния ищите маркеры конфликта, оставленные в виде обычного текста, дублированные блоки элементов, соединенные без запятой, а также удаленные разделители при выборе одной стороны. Осмотрите токен перед указанным местоположением и посчитайте границы окружающего контейнера. Сделайте одно исправление, повторно запустите проверку и сохраните исходный результат, потому что синтаксический анализатор обычно сообщает только о первом препятствии, а второй независимый конфликт может остаться дальше.
Рабочий пример: package.json после неудачного слияния.
Рабочий пример: package.json после неудачного слияния — дублированный блок зависимостей, отсутствующая запятая, отчет валидатора и исправление. Представьте себе, что за `"scripts":{"test":"vitest"}` сразу следует `"dependencies":{"vite":"7.3.6"}`. Второе имя свойства — это то место, где анализатор обнаруживает, что в объекте отсутствует разделитель, хотя корректирующая запятая стоит после объекта скриптов.
Вставьте эту запятую и еще раз проверьте перед форматированием. Если в результате слияния также были созданы два ключа `dependencies`, строгий анализ все равно может быть успешным, поскольку повторяющиеся имена синтаксически разрешены, однако анализ JavaScript сохраняет только более позднее значение. Сравните обе ветви и объедините нужные элементы, а не удаляйте блок механически. Исправление синтаксиса и разрешение семантического слияния — это последовательные, отдельные задачи.
Сделайте валидацию привычкой
Сделайте проверку привычкой — вставляйте ее перед фиксацией или проверяйте любой JSON, который вы редактировали за пределами IDE, без необходимости использования учетной записи или плагина. Лучший триггер — поведенческий: всякий раз, когда маркеры конфликта были разрешены, большой блок был перемещен или знаки препинания были набраны вручную, запускайте проверку владеющего инструмента или строгий парсер перед размещением файла.
Репозитории могут автоматизировать одно и то же правило с проверкой перед фиксацией и заданием CI, ограниченным манифестами, но автоматизация должна дополнять немедленную обратную связь, а не становиться первым анализатором. Держите форматирование отдельно от восстановления, чтобы разница отображала значимый символ. Для сгенерированных файлов выполните повторную генерацию из исходного манифеста вместо нормализации отредактированного вручную вывода, а затем позвольте генератору доказать свои собственные инварианты.
Что это не распространяется
На что это не распространяется — семантические ошибки, такие как неправильный диапазон версий или неизвестное поле, от которых действительный JSON не может защитить вас. Манифест пакета может анализироваться при присвоении имени несуществующему сценарию, размещении зависимости в неправильном разделе или использовании выражения версии, которое неожиданно разрешается. Дублирующиеся ключи также могут проходить проверку грамматики, автоматически заменяя предыдущие значения.
Используйте проверку менеджера пакетов, схемы, устанавливайте тесты и проверяйте эти уровни. Эта проверка также не доказывает, что файл блокировки соответствует его манифесту или что конфигурация запуска называет установленный отладчик. Если фактический формат — JSONC или другой диалект, используйте его анализатор, а не удаляйте поддерживаемый синтаксис просто для удовлетворения строгого JSON. Грамматика — это самые ранние ворота, а не полный контракт конфигурации.
Вывод: проверка синтаксиса стоит секунды, неисправный конвейер стоит несколько минут.
Вывод: проверка синтаксиса стоит секунды, неисправный конвейер стоит несколько минут, а точный отчет валидатора сокращает время исправления. Запустите его на последних отредактированных байтах, начните с указанной строки и столбца, затем проверьте предыдущий токен на предмет отсутствия разделителя или разделителя. Выполняйте повторную проверку после каждого исправления, поскольку более поздние ошибки могут быть изначально скрыты.
После прохождения строгого синтаксиса вернитесь к потребителю: запустите менеджер пакетов, компилятор или специальную проверку редактора, которая понимает разрешенные поля и значения. Делайте ремонтные различия узкими, особенно после слияний, чтобы рецензенты могли отличать пунктуацию от решений о зависимостях. Эта последовательность локально отлавливает самый дешевый сбой и резервирует дорогостоящее время конвейера для поведения, которое может оценить только вся среда.