# Каталог программ

Репозиторий хранит дистрибутивы программ и их метаданные. Все пользовательские
названия и описания пишутся на русском языке. Официальные названия программ,
версии, имена платформ и другие технические значения переводить не нужно.

## Структура

Корень репозитория одновременно является корнем каталога программ. Вложенность
категорий не ограничена. Имя папки служит стабильным машиночитаемым
идентификатором: используйте строчные латинские буквы, цифры, дефис и
подчёркивание.

```text
./
├── index.yaml
├── schema/
│   └── index.schema.json
└── system/
    ├── index.yaml
    └── file-managers/
        ├── index.yaml
        └── example-program/
            ├── index.yaml
            ├── img/
            │   └── screenshot.png
            └── files/
                ├── example-program-1.0.0.zip
                ├── example-program-1.1.0.zip
                └── manual.pdf
```

Каждая категория и каждая программа содержит ровно один `index.yaml`:

- `type: category` означает категорию; рядом могут находиться подкатегории и
  программы;
- `type: program` означает программу; все её версии описываются в этом же
  файле;
- `img` и `files` — зарезервированные папки внутри программы.

Папки без `index.yaml`, например корневая `schema`, не входят в дерево
категорий.

Список дочерних элементов категории не дублируется в YAML: он определяется по
вложенным папкам. Благодаря этому перемещение программы не требует правки
родительских индексов.

## Категория

```yaml
format: 1
type: category
name: Системные программы
description: Утилиты для настройки и обслуживания устройства.
```

## Программа

```yaml
format: 1
type: program
name: Пример программы
description: |-
  Краткое описание назначения и возможностей программы.

  Возможности:
  - первая возможность;
  - вторая возможность.
homepage: https://example.org/program
source: https://github.com/example/program
screenshots:
  - img/screenshot.png
versions:
  - version: "1.1.0"
    status: current
    released: "2007-08-14"
    files:
      - path: files/example-program-1.1.0.zip
        description: Дистрибутив программы
        platform: win32
        sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
  - version: "1.0.0"
    files:
      - path: files/example-program-1.0.0.zip
additional_files:
  - path: files/manual.pdf
    description: Руководство пользователя
```

Обязательные поля программы: `format`, `type`, `name`, `description`,
`screenshots`, `versions`. Поля `homepage`, `source` и `additional_files`
необязательны.

Поле `description` содержит Markdown. Для содержательного описания используйте
абзацы и списки внутри литерального YAML-блока `|-`.

Все файлы программы хранятся в её папке `files`. Версионные файлы перечислены
в `versions[].files`, а не зависящие от версии — в `additional_files`. Один и
тот же файл не следует указывать в обоих местах. Новые версии добавляются в
начало массива `versions`, от новых к старым.

Необязательное поле файла `platform` использует короткие машиночитаемые
значения: `win32`, `win64`, `dos`, `java` или `j2me`. Отдельного поля
архитектуры нет: разрядность Windows уже включена в `win32` или `win64`.

Необязательное поле `status` принимает значение `current` для актуальной версии
или `archived` для версии, оставленной в каталоге как архивная. Если программа
использует статусы, они указываются у всех её версий.

`description` версии используется только для существенных исключений, которые
нельзя выразить номером версии или описанием файла. Обычный список изменений в
индекс не переносится.

Скриншоты хранятся в `img`; пути всегда начинаются с `img/`. Если скриншотов
нет, указывается пустой массив: `screenshots: []`.

## Правила формата

- Кодировка всех YAML-файлов — UTF-8, окончания строк — LF.
- `format` — версия формата метаданных. Текущее значение: `1`.
- Неизвестные поля запрещены: расширение формата требует изменения схемы.
- Все пути задаются относительно папки программы. Абсолютные пути, `..` и
  обратная косая черта запрещены.
- Даты записываются строкой `YYYY-MM-DD` и берутся в кавычки.
- URL используют только `http` или `https`.
- `sha256`, если указан, содержит 64 шестнадцатеричных символа в нижнем
  регистре.
- Массивы не должны содержать дубликаты.
- Описания программы, версии и файла пишутся на русском языке.

Архивы хранятся через Git LFS, остальные файлы — как обычные объекты Git.

## Заполнение SHA-256

Для установки зависимостей используется pnpm:

```shell
pnpm install
```

Команда вычисляет контрольные суммы всех файлов из `versions` и
`additional_files`, после чего добавляет или обновляет поля `sha256`:

```shell
pnpm sha256
```

Можно ограничить обход одной программой, категорией или конкретным индексом:

```shell
pnpm sha256 service/repair-tools/joker
pnpm sha256 service/repair-tools/joker/index.yaml
```

Для проверки без изменения YAML используется отдельная команда:

```shell
pnpm sha256:check
```

## Дерево каталога

Дерево категорий и программ строится по файловой структуре и названиям из
`index.yaml`:

```shell
pnpm tree
```

Можно вывести только выбранную ветку, добавить пути каталогов или версии
программ:

```shell
pnpm tree service/repair-tools
pnpm tree --paths
pnpm tree --versions
```

Формальная JSON Schema находится в
[`schema/index.schema.json`](schema/index.schema.json). Она проверяет структуру
и значения `index.yaml`; соответствие русского текста проверяется при ревью,
поскольку название продукта может состоять из латинских символов.