Codemap-cli

codemap-cli — кроссплатформенная утилита командной строки для создания текстового снепшота репозитория. Инструмент конвертирует дерево файлов в единый структурированный текстовый файл, удобный для анализа, аудита или передачи в сторонние инструменты.

Основные возможности

• обработка игнор-файлов (.gitignore, .gptignore, .codemapignore, .dockerignore), включая вложенные правила
• рекурсивный обход директории
• исключение бинарных файлов
• корректная работа с UTF-8, включая многоязычные комментарии
• вывод в одном текстовом файле с блоками # file: ... и code fences
• встроенный denylist секретов (.env, id_rsa, *.pem и др.) с возможностью отключения
• кроссплатформенная работа (Windows, macOS, Linux)
• возможность глобальной установки и запуска из любой директории
• статистика после генерации (Files, Size, Tokens, Output)

Установка

Глобальная установка

npm install -g codemap-cli

После установки команда codemap становится доступна в $PATH.

Локальная установка в проект

npm install --save-dev codemap-cli

Использование через npx

npx codemap-cli .

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

Создать снепшот текста из текущей директории

codemap .

По умолчанию будет создан файл output.txt в текущей папке.

Указать путь и файл вывода

codemap ./frontend -o frontend.txt

Добавить преамбулу

codemap . -o snapshot.txt -p preamble.txt

Вывести результат в STDOUT

codemap . -o -

Поддерживаемые ignore-файлы

Утилита автоматически обрабатывает следующие файлы в каждой директории дерева:

• .codemapignore
• .gptignore
• .gitignore
• .dockerignore

Формат соответствует синтаксису .gitignore.

Файлы игнора:

• используются как источник правил исключения
• поддерживают вложенные правила и negation-паттерны (!pattern)
• не включаются в итоговый снепшот

Принцип работы

1. Определение корневой директории

Первый позиционный аргумент команды задаёт путь.
Если он отсутствует — используется . (текущая директория).

2. Загрузка ignore-правил

Утилита:

• подгружает стандартные исключения (например, node_modules/, .git/)
• ищет и загружает поддерживаемые ignore-файлы (включая вложенные директории)
• объединяет все правила в единый фильтр

3. Рекурсивный обход дерева

Алгоритм:

• обходит директории с помощью fs.readdirSync и recursive walk
• пропускает игнорируемые пути
• пропускает бинарные файлы (определяются наличием 0x00)

4. Определение типа файла

Язык подсветки для блока определяется по расширению файла:
.js → javascript, .ts → ts, .vue → vue, и т.д.

5. Формирование снепшота

Результат записывается в одном текстовом файле с таким форматом:

# file: src/index.js

```javascript
console.log("example");
```

Опции CLI

| Опция | Описание | | ----------------------- | -------------------------------------------------------------- | | [path] | Путь к каталогу (по умолчанию .) | | -o, --output <file> | Имя файла вывода или - для STDOUT. По умолчанию output.txt | | -p, --preamble <file> | Путь к файлу, содержимое которого будет добавлено в начало | | --allow-secrets | Отключить встроенный denylist секретов | | -v, --version | Показать текущую версию | | -h, --help | Показать справку |

Примеры использования

Генерация текстового слепка фронтенда

cd project/frontend
codemap . -o frontend.txt

Снепшот всей монорепы

codemap . -o repo.txt

Снепшот с преамбулой (например, инструкцией)

codemap . -p docs/header.txt -o summary.txt

Тестирование

Для запуска тестов требуется Node.js v18+.

Запуск:

npm test

Тесты покрывают:

• парсинг аргументов
• обработку игнор-файлов
• определение бинарных/текстовых файлов
• форматирование вывода
• рекурсивный обход каталога

Ограничения

• Бинарные файлы исключаются полностью и не получают даже заголовочного блока.
• Поддержка других форматов вывода (JSON, Markdown-таблица и т.д.) отсутствует в текущей версии.

Лицензия

MIT License