Низкоуровневый пакет. Напрямую он почти никому не нужен — в обычном проекте ECSS подключается через @mart-dev-test-1/vite-plugin, который уже использует этот компилятор под капотом. Ставьте @mart-dev-test-1/compiler вручную, только если пишете собственный тулинг или адаптер.

📦 Установка

npm i -D @mart-dev-test-1/compiler

pnpm add -D @mart-dev-test-1/compiler

yarn add -D @mart-dev-test-1/compiler

🧩 Что это

@mart-dev-test-1/compiler — это движок ECSS. На вход он принимает AST .ecss-файла (его строит @mart-dev-test-1/parser), а на выход выдаёт три артефакта:

• статический CSS — все блоки, элементы и условия, развёрнутые в обычные CSS-правила;
• типизированный JS-модуль — то, что импортируется из .ecss-файла; его рантайм-привязки опираются на хелперы из подпути @mart-dev-test-1/compiler/runtime;
• декларации .d.ts — типы блоков, параметров, enum'ов и констант для TypeScript.

Именно на нём построен @mart-dev-test-1/vite-plugin. Обращаться к компилятору напрямую имеет смысл лишь в одном случае — когда вы строите собственный инструмент сборки или адаптер и вам нужен доступ к стадиям анализа и кодогенерации.

import { parse } from '@mart-dev-test-1/parser';
import { analyze, compile } from '@mart-dev-test-1/compiler';

const ast = parse(source);
const analysis = analyze(ast); // семантическая проверка
const { css, js, dts } = compile(/* … */);

Пакет работает как с одиночными модулями, так и с графом модулей (@import), но не читает файлы с диска и не следит за сборкой — это задача плагина бандлера.

🛠 API

Основные экспорты:

• compile — компилирует один разобранный .ecss-модуль в CSS, JS и .d.ts.
• compileModule — то же, но с учётом связанного контекста (@import из других модулей).
• analyze / SemanticError — семантический анализ AST; SemanticError бросается при ошибках (неизвестный enum, дубликат параметра и т.п.).
• generateDts / generateSharedDts — генерация деклараций TypeScript для модуля и общих (shared) типов.
• CodeBuilder — низкоуровневый билдер кода с отступами и трекингом строк (LineMapping) для кодогенерации.
• jsdocBlock — формирует JSDoc-комментарий для генерируемого кода.
• buildAdapterInput — собирает нормализованный вход адаптера (AdapterInput) из результатов анализа.
• buildModuleGraph / buildFileScope / buildModuleExports — хелперы графа модулей и разрешения @import между файлами.
• substituteConsts, literalToCss, buildSelector, normalizeColor, buildDebugTree, сорсмап-утилиты — вспомогательные функции отдельных стадий компиляции.
• Типы — EcssAdapter, AdapterInput, AdapterOutput, EcssStylesheet, BlockDecl, ResolvedBlock, ParamDecl, EnumDecl, CompileResult и десятки других узлов AST и контрактов адаптера.

Подпуть @mart-dev-test-1/compiler/runtime

import { createBlock, checkParams } from '@mart-dev-test-1/compiler/runtime';

Лёгкие рантайм-хелперы, которые вызывает сгенерированный JS-модуль во время выполнения: createBlock / createBlockWithValidation собирают результат блока, checkParams валидирует переданные параметры, ecssLog / ecssWarn — логирование. Отдельно их импортировать почти никогда не нужно.

👨‍💻 Автор

Разработка и поддержка: Руслан Мартынов

Если нашёл баг или есть предложение — открывай issue или отправляй pull request.

📄 Лицензия

Распространяется под лицензией MIT.