index/README.md

# Индекс метаданных и модулей конфигураций 1С

**Версия:** см. [`VERSION`](VERSION) (текущая: **0.3.2**) · [CHANGELOG](CHANGELOG.md)  
**Автор:** Michael BAG · [mk@p7net.ru](mailto:mk@p7net.ru)  
**Лицензия:** [GNU GPL v3](LICENSE) · [русский перевод (справочно)](LICENSE.ru)

Единый кэш проекта: **`cache/1c_meta/index.sqlite`** — все выгрузки 1С в одной БД (SQLite FTS5).

| Скрипт | Назначение |
|--------|------------|
| [`index_1c.py`](index_1c.py) | построение и обновление индекса |
| [`query_1c.py`](query_1c.py) | поиск и просмотр по готовому индексу |

```bash
python index_1c.py --version
python query_1c.py --version
```

---

## Зачем это нужно

Обход десятков тысяч XML/BSL в `<выгрузка>/src` через Grep в IDE медленный. Индекс один раз разбирает метаданные и модули и даёт:

| Задача | Команда |
|--------|---------|
| Найти объект по имени/синониму | `query_1c.py search` / `object` |
| Структура реквизитов, обязательность, типы | `query_1c.py object` |
| Кто ссылается на справочник/документ | `query_1c.py refs` |
| Документ ↔ регистры движений | `query_1c.py movements` |
| Найти процедуру/фрагмент в BSL | `query_1c.py modules` |
| Сравнить несколько выгрузок в одном репозитории | `-b cfg1 -b cfg2` |

**Типичный workflow:**  
`reindex` (после выгрузки) → `object` / `search` → `refs` / `modules` → открыть конкретный `.xml` / `.bsl`.

---

## Параметры командной строки (общие)

| Параметр | Короткий | Назначение |
|----------|----------|------------|
| `--config` | `-c` | Файл **настроек утилиты** (YAML). **Не** конфигурация 1С. См. [`config.example.yml`](config.example.yml). |
| `--root` | `-r` | Корень проекта с выгрузками 1С (если запуск не из дерева проекта). |
| `--baseconf` | `-b` | Выгрузка конфигурации 1С: папка `<name>/src/` в репозитории. Можно несколько раз. |
| `--version` | | Версия утилиты. |

Приоритет корня проекта: `--root` > `project_root` в `--config` > авто (каталог с `index_1c.py` и `VERSION`).
Если `--config` не указан, утилита пытается автоматически найти
`config.local.yml`, `config.local.yaml` или `config.local.json`.

### Алиасы `--baseconf`

Краткие имена задаются в файле `--config`, поле **`baseconf_aliases`**:

```yaml
project_root: "/path/to/project"
baseconf_aliases:
  main: "my-config"
  ext: "my-config.ext"
```

После этого `-b main` эквивалентно `-b my-config`.

Если в YAML задан блок `default_baseconfs`, то `reindex` без `-b` использует этот список.
Если блока нет — `reindex` без `-b` индексирует **все** каталоги с `src/` в корне проекта.
`query_1c.py` без `-b` ищет по **всем** конфигурациям в индексе.

Список выгрузок: `python index_1c.py list`

---

## `index_1c.py` — переиндексация

### Команды

| Команда | Описание |
|---------|----------|
| `reindex` | обновить индекс |
| `status` | размер БД, meta, список проиндексированных baseconf |
| `list` | выгрузки с `src/` в репозитории + что уже в индексе |

### Режимы `reindex`

| Вызов | Поведение |
|-------|-----------|
| `reindex -j 12` | инкремент: только файлы с изменившимися `mtime`/`size` |
| `reindex --full -j 12` | удалить всю БД и собрать заново все известные выгрузки |
| `reindex --full -b my-config` | пересобрать только указанную конфигурацию |
| `reindex -b main -t Documents,Catalogs` | только выбранные типы объектов |
| `reindex -b my-config --no-modules` | метаданные без BSL |
| `reindex --md` | дополнительно Markdown в `cache/1c_meta/md/<baseconf>/` |

`-j` / `--workers` — число потоков (по умолчанию 4–16).

### Что индексируется

- **Метаданные** `src/<Тип>/*.xml`: имя, синоним, комментарий, реквизиты / измерения / ресурсы / ТЧ, типы (в т.ч. `TypeSet`), ссылки, `FillChecking`, `RegisterRecords` (документ → регистры движений).
- **Модули** `**/*.bsl`: путь, owner (`Document.X`), вид модуля, имена процедур/функций, тело (до 200 КБ в FTS).
- **Связи движений** — таблица `register_records` (обратный индекс регистраторов).

По умолчанию пропускаются: `CommonPicture`, `StyleItem`, `XDTOPackage`, `CommonTemplate`, `Language`, `Bot`.

### Примеры переиндексации

```bash
# после обновления одной выгрузки
python index_1c.py reindex -b my-config -j 12

# полная пересборка всего проекта
python index_1c.py reindex --full -j 12

# основная конфигурация + расширение, только документы и справочники
python index_1c.py reindex -b main -b ext -t Documents,Catalogs -j 8

python index_1c.py status
python index_1c.py list
```

---

## `query_1c.py` — поиск

Нужен готовый `cache/1c_meta/index.sqlite`.

### Команды

| Команда | Аргумент | Результат | Полезные опции |
|---------|----------|-----------|----------------|
| `search` | строка | объекты метаданных (FTS) | `-b`, `--type`, `--limit` |
| `object` | имя/синоним объекта **или** реквизита | дерево структуры | `-b`, `--type`, `--clear`, `--limit` |
| `show` | имя объекта | полная карточка JSON | `-b` |
| `refs` | `Catalog.Customers` / `Contract` | обратные ссылки полей | `-b`, `--limit` (на каждую baseconf) |
| `movements` | документ или регистр | регистратор ↔ регистры движений | `-b`, `--type`, `--limit` |
| `modules` | строка | поиск по BSL | `-b`, `-n` / `--names-only`, `--limit` |
| `module` | путь или owner | символы модуля, строки | `-b` |

### `object` — дерево реквизитов

```bash
# полная структура документа
python query_1c.py object Contract -b my-config

# только реквизиты с именем/синонимом «Partner» в документах
python query_1c.py object Partner -b my-config --type Document --clear

# совпал сам объект → --clear печатает только заголовок
python query_1c.py object Contract -b my-config --clear
```

Формат строки реквизита:

```text
├── `Attribute.Partner` — Клиент [обяз.] : CatalogRef.Customers
├── `Attribute.Amount` — … [необяз.] : DefinedType.MoneyAmount
├── `TabularSection.Lines` — Строки
│   └── `Column.Item` — … [обяз.] : CatalogRef.Items
```

- **[обяз.]** — `FillChecking=ShowError`; **[необяз.]** — `DontCheck`
- составной тип: несколько вариантов через `|`
- при наличии XML структура подтягивается с диска (актуальный `FillChecking`)

### `refs` — кто ссылается

```bash
python query_1c.py refs "Contract"
python query_1c.py refs Catalog.Customers -b my-config --limit 50
python query_1c.py refs Document.Contract -b main
```

Без `-b` — все конфигурации в индексе; `--limit` действует **на каждую**.  
Составной тип поля: `→ DocumentRef.Contract (среди прочего: DocumentRef.…)`.

### `movements` — регистратор ↔ регистры движений

```bash
# документ → регистры, в которых он регистратор
python query_1c.py movements Contract -b my-config
python query_1c.py movements Document.Sales -b my-config

# регистр → документы-регистраторы
python query_1c.py movements AccumulationRegister.Stock -b my-config
python query_1c.py movements Stock -b my-config --type AccumulationRegister
```

Данные из свойства метаданных `RegisterRecords` (таблица `register_records` в индексе).  
При первом запуске утилиты v0.3+ схема индекса мигрирует 2→3 автоматически (без полного `reindex`).

### `modules` / `module`

```bash
python query_1c.py modules "ProcessData" -b my-config
python query_1c.py modules "MyModule" -b my-config.ext -n
python query_1c.py module CommonModules/MyModule -b my-config
```

### Прочие примеры

```bash
python query_1c.py search "Contract"
python query_1c.py search "Partner" --type Document -b my-config
python query_1c.py show Document.Contract -b main
python query_1c.py search "Partner" -b main -b ext
```

### Ошибки и подсказки

| Ситуация | Поведение |
|----------|-----------|
| Нет `index.sqlite` | подсказка `index_1c.py reindex --full` |
| `-b` без папки `src/` | список доступных выгрузок |
| `-b` есть в репо, нет в индексе | список проиндексированных + команда `reindex -b …` |
| `show` / `object` не нашли | похожие имена из индекса |

---

## Файл настроек утилиты (`--config`)

```bash
cp config.example.yml config.local.yml
# project_root: "/path/to/project"
python query_1c.py --config config.local.yml search "Contract"
```

`config.local.yml` в `.gitignore` (локальные пути и алиасы).
Legacy-вариант `config.local.json` тоже поддерживается и подхватывается авто-поиском.

---

## Применение в Cursor / IDE

1. После выгрузки из EDT/конфигуратора: `python index_1c.py reindex -j 12` (или `-b my-config`).
2. Метаданные и связи — через `query_1c.py`, не Grep по всему `src/`.
3. При нескольких выгрузках — ограничивать `-b` нужной baseconf.
4. Код: `modules` → открыть `rel_path`; структура документа: `object`.

---

## Артефакты кэша

```text
cache/1c_meta/          # в корне проекта (обычно в .gitignore)
  index.sqlite          # единая БД
  INDEX.md
  manifest.json
  md/<baseconf>/        # опционально (--md)
```

Per-config `search.sqlite` устарели и не используются.

---

## Автор и обратная связь

| | |
|---|---|
| **Автор** | Michael BAG |
| **E-mail** | [mk@p7net.ru](mailto:mk@p7net.ru) |
| **Предложения, вопросы, ошибки** | пишите на **mk@p7net.ru** |

---

## Лицензирование

Программа **index_1c.py**, **query_1c.py** и пакет **index1c/** распространяются на условиях
**GNU General Public License версии 3** (или более поздней).

| Файл | Язык | Статус |
|------|------|--------|
| [`LICENSE`](LICENSE) | английский | **юридически значимый** текст лицензии (FSF) |
| [`LICENSE.ru`](LICENSE.ru) | русский | **неофициальный перевод** для ознакомления |

Юридическую силу имеет только английский текст [`LICENSE`](LICENSE).
Русский перевод [`LICENSE.ru`](LICENSE.ru) не опубликован FSF и не заменяет оригинал;
он помогает русскоязычным пользователям понять условия GPL v3.

**Copyright © 2025–2026 Michael BAG** \<mk@p7net.ru\>

При распространении или модификации сохраняйте уведомление об авторских правах и текст лицензии.
Производные работы должны распространяться на тех же условиях GPL v3.