# vue-cssgen

[![npm version](https://img.shields.io/npm/v/vue-cssgen.svg)](https://www.npmjs.com/package/vue-cssgen)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

---

## Описание

**vue-cssgen** — CLI-инструмент для автоматизации и структурирования CSS в проектах на Vue 3.

* Анализирует компоненты, извлекает классы из шаблонов и `<style>`.
* Автоматически генерирует, оптимизирует и выносит CSS в локальные и глобальные файлы по правилам и встречаемости.
* Умеет работать как с автоклассами по правилам (аналог Tailwind), так и с любыми кастомными классами.
* Управляет глобализацией: популярные классы попадают в глобальные стили, редкие остаются локально.
* Сохраняет статистику по классам, помогает находить неиспользуемые стили ("мертвые" классы).
* Позволяет легко расширять и переопределять генерацию под любые требования проекта.

---

## Возможности

* **Групповой и одиночный запуск:** работает с одной директорией, списком директорий/файлов, либо с отдельным файлом.
* **Статистика классов:** сохраняет подробные json-файлы по автоклассам, пользовательским и неиспользуемым.
* **Гибкая конфигурация:** настраиваемый конфиг, поддержка кастомных правил и исключений.
* **Безопасное обновление стилей:** все глобальные файлы только дополняются, ваши ручные правки не теряются.
* **dryRun-режим:** безопасный анализ без изменений файлов.
* **Поддержка расширения/переопределения любых правил через папку `vue-cssgen-rules`**
* **Автоматический перенос классов между локальными и глобальными файлами в зависимости от количества использований.**

---

## Быстрый старт

1. **Установка:**

```bash
npm install vue-cssgen --save-dev
# или
yarn add vue-cssgen --dev
```

2. **Создай конфиг:**

`vue-cssgen.conf.js` в корне проекта:

```js
export default {
  projectRoot: "./",
  componentsDir: ["./src/components", "./src/pages/Home.vue"], // массив путей к папкам или .vue-файлам
  resultsDir: "vue-css-stat", // директория для статистики
  files: {
    statsAuto: "stats-auto.json",
    statsCustom: "stats-custom.json",
    statsDead: "stats-dead.json",
  },
  globalCssFile: "./src/assets/css/global.css",
  globalCustomCssFile: "./src/assets/css/global-custom.css",
  dryRun: false,
  logLevel: 'info',
  globalThreshold: 2,
  extractUserCustom: true
};
```

* `componentsDir` — массив путей к папкам и/или отдельным `.vue`-файлам.
* `globalThreshold` — порог вынесения класса в глобальные стили (>= столько компонентов — глобализация).

3. **Добавь npm-скрипт:**

```json
"scripts": {
  "css-gen": "vue-cssgen"
}
```

4. **Запусти:**

```bash
npm run css-gen
# или
npx vue-cssgen
```

5. **Проверь результат:**

* Все локальные и глобальные стили будут актуализированы без потери ручных изменений.
* В каталоге статистики появятся файлы с отчетами по всем классам.

---

## Расширение и кастомизация

### Пользовательские правила

Создай папку `vue-cssgen-rules` в корне проекта. Добавляй свои правила:

```js
// vue-cssgen-rules/project-rules.js
export default [
  {
    match: /^bdc-hex_[a-fA-F0-9]{3,6}$/,
    css: cls => {
      const val = cls.replace('bdc-hex_', '');
      return `.${cls} { border-color: #${val} !important; }`;
    },
    group: 'border',
    desc: 'border-color HEX',
    modifiable: true,
    examples: ['bdc-hex_222', 'bdc-hex_ff0000'],
    values: null,
    prefix: 'bdc-hex_'
  },
];
```

* Файл должен экспортировать массив объектов с ключами: `match` (RegExp), `css` (функция генерации), `group`, `desc` и т.д.
* Все ваши правила объединяются с дефолтными. Совпадающие `match` переопределяют правила из пакета.

### Игнор-листы

Пакет поддерживает white/black/global-игнор-листы в папке `lists/`:

* `whitelist.js`, `blacklist.js`, `globalStyleIgnore.js`

Пример:

```js
// lists/globalStyleIgnore.js
export default function(className) {
  return (
    /^bg-img_/.test(className) ||
    /^private-/.test(className) ||
    className.endsWith('-once')
  );
};
```

---

## Ключевые сценарии использования

* **Один файл:**

```bash
npx vue-cssgen src/components/MyBlock.vue
```

* **Несколько директорий или файлов:**

В конфиге передай массив путей:

```js
componentsDir: ["./src/components", "./src/pages", "./src/SomeComponent.vue"]
```

---

## Как работает обработка

1. Все классы из статических атрибутов `class` в `<template>` парсятся и сравниваются с правилами.
2. Для автоклассов по правилам — генерируется CSS согласно логике пакета/ваших правил.
3. Для пользовательских (непопавших под правила) — сохраняется CSS из `<style>` блока.
4. Популярные классы (кол-во компонентов >= `globalThreshold`) попадают в глобальные стили. Остальные — остаются/переносятся локально.
5. Мёртвые классы из `<style>`, которые не используются в шаблоне, помечаются как `// #мертвый-класс-...`.
6. Все действия фиксируются в статистике (json-файлы в resultsDir).

---

## Дополнительные команды

* **Генерация справочника классов:**

```bash
npx generate-css
```

Создаёт файл `all-classes.css` со всеми доступными автоклассами.

* **Визуальный UI:**

Открой `ui.html` в корне пакета для просмотра всех автоклассов и описаний.

---

## Примеры

### Пользовательский конфиг

```js
// vue-cssgen.conf.js
export default {
  projectRoot: "./",
  componentsDir: ["./src/components"],
  resultsDir: "vue-css-stat",
  files: {
    statsAuto: "stats-auto.json",
    statsCustom: "stats-custom.json",
    statsDead: "stats-dead.json"
  },
  globalCssFile: "./src/assets/css/global.css",
  globalCustomCssFile: "./src/assets/css/global-custom.css",
  dryRun: false,
  logLevel: 'info',
  globalThreshold: 2,
  extractUserCustom: true
};
```

### Пример npm-скрипта

```json
"scripts": {
  "css-gen": "vue-cssgen"
}
```

### Пользовательское правило

```js
// vue-cssgen-rules/my-color.js
export default [
  {
    match: /^c-(red|blue|green)$/,
    css: cls => `.${cls} { color: ${cls.slice(2)}; }`,
    group: 'color',
    desc: 'text color',
    examples: ['c-red', 'c-blue']
  }
];
```

---

## FAQ

* **Как сохраняются ручные правки в глобальных CSS?**
  Все ваши правки в глобальных файлах сохраняются — скрипт только добавляет новые классы, ничего не перезаписывает.

* **Как добавить или изменить генерацию для класса?**
  Просто добавьте или измените правило в `vue-cssgen-rules`.

* **Что такое dryRun?**
  Если включить, ни один файл не будет изменён. Только вывод статистики и логов.

* **Мёртвые классы?**
  Все классы, которые есть в `<style>`, но не используются в шаблоне, будут помечены комментарием и/или вынесены в отдельную статистику.

* **Как игнорировать динамические классы?**
  Динамические классы `:class` не учитываются, только статические string-классы.

---

## Полезное

* Для крупных проектов сначала используйте dryRun для безопасной проверки.
* Используйте кастомные правила через `vue-cssgen-rules`.
* Настраивайте порог глобализации (globalThreshold) под размер проекта.
* Запускайте инструмент регулярно для поддержания чистоты CSS.

---

**Автор:** Кузьминский Максим П — [i@m-letto.ru](mailto:i@m-letto.ru)

Лицензия: MIT

Проект [vodorod-ai.ru](https://vodorod-ai.ru)