Documentation quality validation: broken links, orphan docs, glossary, structure

GitHub stars
17

Install

/plugin install doc-validate@dapi

Run it inside Claude Code after adding the marketplace with /plugin marketplace add dapi/claude-code-marketplace.

Contents

Discovered from source

Skills 1

Documentation Validation Skill

Комплекс команд /doc:* для автоматической и интерактивной проверки качества проектной документации.

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

# Быстрая проверка перед коммитом
/doc:lint

# Проверка графа связей
/doc:links

# Полный аудит (все проверки)
/doc:review

Команды

/doc:lint — Проверка форматирования

Модель: haiku (быстро, дёшево) Время: < 30 сек для 100 файлов

Проверки:

  • Битые внутренние ссылки [text](file.md)
  • Несуществующие файлы в навигации
  • Нарушения naming conventions (NN_TITLE.md для корневых)
  • Пустые секции (## без контента)
  • TODO/FIXME без ссылки на issue
  • Отсутствие обязательных секций

Пример вывода:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 [LINT-001] Битая ссылка
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 03_REQUIREMENTS.md:45
   > [см. архитектуру](architecture/MISSING.md)

❌ Файл не существует: architecture/MISSING.md

[f]ix  [s]kip  [i]gnore  [e]dit  [g]ithub issue  [x]plain
> _

/doc:links — Граф связей

Модель: haiku Время: < 30 сек для 100 файлов

Проверки:

  • Orphan-документы (без входящих ссылок)
  • Dead-ends (без исходящих ссылок)
  • Циклические зависимости
  • Полнота навигации в README

Исключения (не считаются orphans/dead-ends):

  • README.md, CHANGELOG.md
  • **/GLOSSARY.md, **/INDEX.md
  • Конфигурируется в .docvalidate.yml

Пример вывода:

 Граф документации
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Всего документов: 35
Связей: 128

⚠️ Orphans (нет входящих ссылок):
  - research/old_analysis.md
  - data/transaction-analysis.md

⚠️ Dead-ends (нет исходящих ссылок):
  - architecture/wallet/COMPONENTS.md

✅ README навигация: 28/35 документов (80%)

/doc:terms — Терминология ✅

Модель: sonnet (или haiku для базовых проверок) Требует: глоссарий в 02_GLOSSARY.md

Проверки:

  • Термины из глоссария используются единообразно
  • Обнаружение запрещённых синонимов (кошелёк/wallet/бумажник)
  • Новые термины не в глоссарии (выделенные bold)
  • Покрытие глоссария (% используемых терминов)

Пример вывода:

 Загружен глоссарий: 16 терминов
 Запрещённых синонимов: 5 групп

Сканирование 24 файлов...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 [TERM-001] Запрещённый синоним
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 08_KEY_SECURITY.md:82
   Запрещённый синоним: "wallet" → используйте "кошелёк"

 Покрытие глоссария
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Используется: 14/16 терминов (87%)

/doc:viewpoints — Артефакты ✅

Модель: sonnet

Проверки по viewpoints:

ViewpointАртефактПриоритет
DataSTATE_MACHINES.mdmust
DataDATA_FLOWS.mdshould
Business RulesBUSINESS_RULES.mdmust
SecurityTHREAT_MODEL.mdmust (критично для крипто)
IntegrationEVENT_CATALOG.mdshould
TraceabilityRTM.mdshould

Пример вывода:

## Покрытие Viewpoints

| Viewpoint | Артефакт | Статус | Файл |
|-----------|----------|--------|------|
| Data | STATE_MACHINES | ✅ | architecture/STATE_MACHINES.md |
| Data | DATA_FLOWS | ❌ | architecture/DATA_FLOWS.md |
| Security | THREAT_MODEL | ✅ | architecture/THREAT_MODEL.md |

 Общее покрытие viewpoints: 3/6 (50%)

 Security viewpoint не полностью покрыт — критично для крипто-системы!

/doc:contradictions — Противоречия ✅

Модель: sonnet (локальный анализ) Время: < 60 сек для 100 файлов

Проверки:

  • Конфликтующие значения (разные числа для одного параметра)
  • Взаимоисключающие требования
  • Решения противоречащие ограничениям
  • Числовые параметры с разными значениями в разных документах

Пример вывода:

⚡ /doc:contradictions — Поиск противоречий

 Извлечение параметров из документации...
   Найдено 194 параметров в 25 файлах

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 КРИТИЧНЫЕ ПРОТИВОРЕЧИЯ
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 [CONTRADICTION-001] Параметр "confirmations" имеет разные значения
    03_REQUIREMENTS.md:45 → 3
    architecture/FLOWS.md:128 → 6
   ⚠️ Разница: 100%

 [CONTRADICTION-002] Параметр "hot_wallet_limit" имеет разные значения
    03_REQUIREMENTS.md:52 → 10%
    08_KEY_SECURITY.md:23 → 5%
   ⚠️ Разница: 100%

 Итого: 8 критичных, 10 предупреждений

/doc:gaps — Полнота ✅

Модель: sonnet (локальный анализ) Время: < 60 сек для 100 файлов

Проверки:

  • Упомянутые но не раскрытые темы
  • Требования без acceptance criteria
  • Сущности без полного описания артефактов
  • Интеграции без Event Catalog

Пример вывода:

️ /doc:gaps — Анализ полноты покрытия

 Сканирование документации на гапы...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ПРЕДУПРЕЖДЕНИЯ (требуют внимания)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 [GAP-001] Найдены интеграции (69), но нет Event Catalog
    architecture/EVENT_CATALOG.md — отсутствует
    Рекомендация: создайте EVENT_CATALOG.md для документирования событий

 Итого: 0 критичных, 1 предупреждение

/doc:review — Полный аудит ✅

Модель: все (каскад) Время: < 5 мин для 100 файлов

Запускает все проверки в оптимальном порядке:

  1. lint + links (Phase 1: базовые)
  2. terms + viewpoints (Phase 2: семантические)
  3. contradictions + gaps (Phase 3: глубокий анализ)

Функции:

  • Агрегация результатов всех команд
  • Сводная таблица по категориям
  • Сравнение с предыдущим запуском
  • Рекомендации по приоритетам
  • Общая оценка качества (0-100)

Пример вывода:

╔══════════════════════════════════════════════════════════════╗
║                ИТОГОВЫЙ ОТЧЁТ DOC:REVIEW                   ║
╚══════════════════════════════════════════════════════════════╝

┌────────────────┬──────────┬──────────┬──────────┐
│ Команда        │  Крит. │  Важн. │  Инфо  │
├────────────────┼──────────┼──────────┼──────────┤
│ lint           │        0 │        6 │       92 │
│ links          │        0 │        0 │        0 │
│ terms          │        0 │      194 │       10 │
│ viewpoints     │        0 │        3 │        0 │
│ contradictions │        8 │       10 │        0 │
│ gaps           │        0 │        1 │        0 │
├────────────────┼──────────┼──────────┼──────────┤
│ ИТОГО          │        8 │      214 │      102 │
└────────────────┴──────────┴──────────┴──────────┘

 Покрытие viewpoints: 3/6 (50%)
 Покрытие глоссария: 94%

⏱️  Время выполнения: 0.4 сек

 Рекомендации:
  •  Исправьте 8 критических проблем в первую очередь
  • ⚡ Разрешите противоречия в числовых параметрах
  •  Увеличьте покрытие viewpoints (сейчас 50%)

╔══════════════════════════════════════╗
║      ОБЩАЯ ОЦЕНКА: 85/100 (B)      ║
╚══════════════════════════════════════╝

CLI режимы

# Стандартный режим (вывод без интерактива)
./doc_validate.rb lint

# Интерактивный режим (промпт для каждой проблемы)
./doc_validate.rb lint --interactive

# Batch режим для CI/CD (без вывода, с exit codes)
./doc_validate.rb lint --batch
# Exit codes: 0=ok, 1=warnings, 2=critical

Интерактивный режим

Активация: --interactive или -i

При обнаружении проблемы:

КлавишаДействиеОписание
ffixПрименить автоисправление (если доступно)
sskipПропустить, не исправлять сейчас
iignoreДобавить в .docignore
eeditОткрыть файл в $EDITOR
xexplainПодробнее объяснить проблему

Доступные автоисправления

Тип проблемыДействие fix
broken_linkFuzzy search похожих файлов или удаление ссылки
synonymЗамена на canonical термин
empty_sectionУдаление пустой секции (с подтверждением)

Edge Cases

СитуацияПоведение
fix недоступенПоказать "(fix unavailable)"
Ctrl+CСохранить прогресс в session.json

Конфигурация

Файл .docvalidate.yml в корне проекта:

version: 1

# Глоссарий
glossary:
  file: "02_GLOSSARY.md"
  forbidden_synonyms:
    - ["кошелёк", "wallet", "бумажник"]
    - ["транзакция", "tx", "перевод"]

# Scope проверки
scope:
  strict:
    - "*.md"
    - "architecture/**/*.md"
  relaxed:
    - "research/**/*.md"
    trigger: on_change
  ignore:
    - "claudedocs/**"

# Исключения для orphan/dead-end
link_exceptions:
  not_orphans:
    - "README.md"
    - "CHANGELOG.md"
    - "**/GLOSSARY.md"

# Naming conventions
formatting:
  root_naming: "^[0-9]{2}_[A-Z_]+\\.md$"

Data Model

.docvalidate/.docignore — игнорируемые проблемы

Формат: JSON Lines

{"id": "LINT-001", "file": "research/old.md", "reason": "Архивный", "created": "2025-01-30"}

.docvalidate/history.json — история метрик

{
  "runs": [{
    "timestamp": "2025-01-30T10:30:00Z",
    "metrics": {"critical": 2, "warning": 5, "info": 8}
  }]
}

Error Handling

Fallback chain для AI

opus (недоступен) → sonnet → haiku → native (без AI)

Offline mode

При --offline или отсутствии сети:

  • ✅ /doc:lint — работает полностью
  • ✅ /doc:links — работает полностью
  • ⚠️ /doc:terms — только forbidden_synonyms
  • ❌ /doc:contradictions — недоступна
  • ❌ /doc:gaps — недоступна

Приоритеты проблем

ПриоритетКатегории
Критичныеcontradictions, gaps, missing_threat_model
Важныеduplicates, terms, missing_state_diagrams
Информацияbroken_links, formatting, orphans

Ограничения текущей версии (v1.1.0)

ФункцияСтатусПримечание
Интерактивный режим✅f/s/i/e/x работают
Batch mode + exit codes✅Для CI/CD
Автоисправления✅broken_link, synonym, empty_section
Mermaid граф❌ RoadmapВизуализация link graph
Session recovery❌ RoadmapВозобновление после Ctrl+C
Unit-тесты❌ RoadmapПокрытие 0%

Связанная документация

  • Issue #7 — Основная спецификация
  • Issue #12 — План доработок

Commands 1

Documentation Validation

Запусти Ruby скрипт для валидации документации проекта.

Алгоритм

  1. Найди скрипт:

    SKILL_DIR=$(dirname "$(find ~/.claude -name "doc_validate.rb" -type f 2>/dev/null | head -1)")
    
  2. Спроси пользователя какую проверку запустить:

КомандаОписаниеКогда использовать
lintФорматирование, битые ссылки, namingБыстрая проверка перед коммитом
linksГраф связей, orphans, dead-endsПроверка навигации
termsТерминология, глоссарий, синонимыПосле добавления новых терминов
viewpointsBABOK артефакты, state diagramsПроверка полноты моделирования
contradictionsКонфликты значений, противоречияПоиск несоответствий
gapsПолнота покрытия, missing sectionsАнализ пробелов
reviewПолный аудит (все проверки + оценка)Перед релизом
  1. Выполни выбранную команду:

    ruby "$SKILL_DIR/doc_validate.rb" <command> --project="$(pwd)"
    
  2. Для интерактивного режима добавь --interactive:

    ruby "$SKILL_DIR/doc_validate.rb" <command> --interactive --project="$(pwd)"
    

Режимы

  • Default: Показывает все проблемы
  • Interactive (--interactive): Для каждой проблемы предлагает действия:
    • [f]ix — автоисправление (если доступно)
    • [s]kip — пропустить
    • [i]gnore — добавить в .docignore
    • [e]dit — открыть в редакторе
    • [x]plain — подробнее
  • Batch (--batch): Для CI/CD, exit codes: 0=ok, 1=warnings, 2=critical

Быстрые команды

Если пользователь сразу указал что проверять:

  • /doc-validate lint → сразу запустить lint
  • /doc-validate review → сразу запустить полный аудит
  • /doc-validate links --mermaid → граф с Mermaid диаграммой

Конфигурация

Проверь наличие .docvalidate.yml в корне проекта. Если нет — предложи создать из шаблона.

Sponsors

Details

Marketplace
dapi/claude-code-marketplace
Source
doc-validate
Category
Community

More from dapi/claude-code-marketplace

All 12