Add "Parsing"

Parsing.md

@@ -0,0 +1,135 @@
+# Парсинг и утилиты (parsing.js)
+
+## Обзор
+
+`parsing.js` — ядро работы с Pug-кодом. Парсит блоки, миксины, аргументы, секции, поля.
+
+## Парсинг блоков
+
+### parseBlocks(text)
+Разбивает текст Block.pug на отдельные блоки:
+- Разделитель: строка начинающаяся с `//`
+- Имя блока: текст после `//`
+- Содержимое: все строки до следующего `//`
+- Фильтр: блоки "Доп. текст" исключаются
+
+## Работа с миксинами
+
+### getMixinName(line)
+Извлекает имя: `+buttonRounded(...)` → `"buttonRounded"`
+
+### getMixinArgCount(line)
+Считает аргументы (учитывая вложенные скобки и кавычки), макс 12.
+
+### findMixinArgRange(line, argIndex)
+Находит позицию n-го аргумента в строке. Обрабатывает:
+- Вложенные скобки `(())`
+- Вложенные фигурные скобки `{{}}`
+- Строки в одинарных и двойных кавычках
+- Запятые как разделители
+
+Возвращает: `{start, end}` — позиции в строке.
+
+### extractMixinArgValue(line, argIndex)
+Получает значение аргумента, убирая кавычки.
+
+### replaceMixinArgQuoted(line, argIndex, newValue)
+Заменяет значение аргумента, сохраняя кавычки.
+
+### replaceMixinArgRaw(line, argIndex, newValue)
+Заменяет значение без добавления кавычек.
+
+### replaceObjectPropInArg(rawArg, key, newValue)
+Заменяет значение свойства в объектном аргументе:
+```
+{hidePrice: true, showOldPrice: false} → {hidePrice: false, showOldPrice: false}
+```
+
+## Определение типов полей
+
+### guessAutoMixinField(rawArg, argIndex)
+Автоопределение типа по содержимому:
+- Запятые + цифры → `mixin-ids`
+- `{` → объект (парсить отдельно)
+- `http` / `/` → `mixin-href`
+- Иначе → `mixin-text`
+
+### guessObjectFieldByKey(key, value)
+По имени ключа:
+- `url`, `href`, `link` → `href`
+- `src`, `image`, `img` → `src`
+- Иначе → `text`
+
+### shouldExposeObjectField(key)
+Фильтрует служебные ключи: `class`, `style`, `id`, `data-*` → false.
+
+### parseMixinObjectArg(rawArg)
+Парсит `{key: "value", key2: value2}` → `[{key, value, raw}]`.
+
+### parseQuotedArgs(line)
+Находит все строковые аргументы с их позициями в строке.
+
+## Парсинг текстовых полей
+
+### splitTextField(line)
+Находит текстовое содержимое после Pug-тега:
+```
+span.font.h2.blackText ТЕКСТ → {tagEnd: 25, text: "ТЕКСТ"}
+```
+
+### getParagraphMeta(line)
+Возвращает метаданные текстового поля. Исключает структурные теги (`tr`, `td`, `table`, `thead`, `tbody`, `th`).
+
+## Парсинг списков
+
+### getListItemRanges(lines)
+Находит элементы списков — группы строк формата:
+```pug
+tr
+  tdFixed(width="...")
+    span.text ТЕКСТ
+```
+Возвращает: `[{start, end}]` — диапазоны строк для каждого элемента.
+
+### getListItemTextLine(lines, range)
+Находит строку `span.text` внутри элемента списка.
+
+## Парсинг секций
+
+### parseSections(content)
+Разбирает сложные блоки (карточки товаров) на секции:
+1. Определяет уровень вложенности (indent)
+2. Ищет `tr` на целевом indent
+3. Группирует строки между `tr` и `+spacerLine` в секции
+4. Определяет количество колонок
+
+### parseAtIndent(lines, targetIndent)
+Парсит структуру на заданном уровне:
+- `tr` → начало секции
+- `+spacerLine(N)` → спейсер между секциями
+
+### guessSectionLabel(lines)
+Определяет тип секции по содержимому:
+- `+button` → "Кнопка"
+- `img(` → "Картинка"
+- `+products` → "Товары"
+- `h1/h2/h3` → "Заголовок"
+- `span.text` → "Текст"
+- Иначе → "Ссылка"
+
+### rebuildContentFromSections(parsed)
+Собирает контент блока обратно из разобранной структуры секций.
+
+### normalizeSpacers(sections, topVal, bottomVal)
+Нормализует значения спейсеров между секциями.
+
+## Mixin Rules
+
+### normalizeMixinRules(rules)
+Валидирует массив правил: проверяет наличие `mixin` и `args`, нормализует типы.
+
+### getMixinRulesForLine(line, mixinRules)
+Находит правила, применимые к данной строке миксина. Матчит по имени миксина.
+
+### getDefaultMixinFieldLabel(type)
+Дефолтные лейблы: `mixin-text` → "Текст", `mixin-href` → "Ссылка", `mixin-ids` → "ID", `mixin-opts` → "Опции".