Можно ли доверять автоматической документации репозитория?

Археология репозитория позволяет восстановить удивительно много документации, но один лишь просмотр дополнительных файлов не раскрывает замысел. Карта модулей, статический граф вызовов, предполагаемая модель данных и значительная часть графа зависимостей пакетных заданий опираются на проверяемые свидетельства. Названия вроде «клиент», утверждения о безопасном перезапуске задания и объяснения причин той или иной ветки остаются гипотезами, пока их не подтвердит другой источник.

Эта граница важна, потому что с обеих ее сторон сгенерированная документация звучит одинаково уверенно. Я видел, как команды принимали аккуратную диаграмму, строили вокруг нее план переписывания, а потом обнаруживали, что нужное поведение скрывалось в правиле планировщика или динамически выбранной программе. Отказываться от автоматизации из-за этого не нужно. Каждое сгенерированное утверждение должно содержать свидетельства, метод получения и известные пробелы.

Репозиторий доказывает структуру, но не назначение

Автоматическая документация репозитория заслуживает доверия, когда описывает наблюдаемую структуру и точно указывает способ наблюдения. Файлы, объявления, импорты, цели сборки, ссылки SQL, инструкции JCL и буквальные ключи конфигурации оставляют следы, которые можно проверить. Инструмент способен перечислить их, связать и указать строки, подтверждающие каждую связь.

Назначение устроено иначе. Таблица ACCT_MST может хранить счета клиентов, внутренние бухгалтерские счета или временное состояние сверки. Название подсказывает толкование, но ничего не доказывает. Процедура VALIDATE может отклонять неверный ввод, применять правило авторизации или только проверять ширину полей. Комментарии иногда помогают, но устаревший комментарий остается содержимым репозитория, а не привилегированным источником истины.

В сгенерированной документации я использую три класса доверия:

• Наблюдаемое означает, что в репозитории есть прямое свидетельство, например импорт, EXEC PGM или объявление внешнего ключа.
• Выведенное означает, что несколько наблюдений подтверждают вывод. Например, программы объединены в модуль выставления счетов, потому что используют общие таблицы и точки входа.
• Неразрешенное означает, что репозиторий не дает ответа, даже если одно толкование выглядит вероятным.

Каждый узел и каждое ребро должны ссылаться на источник: путь и строку либо диапазон инструкций. Без происхождения проверяющий не отличит результат парсера от догадки модели. Сгенерированная фраза «INVOICE пишет в AR_LEDGER» полезна, только если читатель может проверить лежащий в ее основе INSERT, вызов хранимой процедуры или запись данных.

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

Карте модулей нужны ребра разных типов

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

Начните с объявленных единиц: проектов, пакетов, библиотек, программ, форм, хранимых процедур, пакетных заданий и целей сборки. Затем соберите типизированные ребра между ними. Полезны типы imports, calls, includes, compiles_into, reads, writes, submits и generates. Сохраняйте тип. Общая таблица слабее подтверждает границу модуля, чем цель сборки, а текстовое включение не равно вызову во время исполнения.

Первым артефактом должен стать машиночитаемый реестр, а не картинка. Например:

{"unit":"billing/post_invoice.cbl","kind":"cobol_program","declares":["POSTINV"],"includes":["ARREC"],"reads":["CUSTOMER"],"writes":["AR_LEDGER"],"evidence":["billing/post_invoice.cbl:18-146"]}

Стройте диаграммы и текст на основе этого реестра. Тогда изменения можно проверить: при перемещении программы или улучшении парсера сначала меняется исходная запись, а за ней все представления. Команда также сможет отправлять запросы к документации вместо изучения графа размером со стену.

Кластеризацию следует применять сдержанно. Связные компоненты, объявления пакетов, префиксы имен, файлы владельцев и единицы развертывания могут предлагать границы. Они не должны незаметно придумывать их. Если программы AR* используют общие записи и развертываются вместе, назовите их выведенным кластером выставления счетов и укажите правило создания. После этого человек сможет принять, разделить или переименовать кластер.

Сгенерированное описание модуля должно отвечать на практические вопросы. Что входит в эту единицу? Что она может вызвать? Какими данными она владеет, а каких только касается? Как ее собирают и развертывают? Какая другая единица сломается при изменении интерфейса? Цветной прямоугольник без ответов на эти вопросы остается украшением.

Статические графы вызовов полезны и предсказуемо неполны

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

Руководство GNU cflow проводит именно такое различие между прямым и обратным графом для C. Оно также позволяет управлять фильтрацией символов и препроцессором. Это уточнение существенно. Граф зависит от анализатора языка, настроек препроцессора, флагов сборки и выбранных точек входа. Запуск парсера с настройками по умолчанию на всех файлах не равен анализу программы, которую собирают для промышленной среды.

Первый крупный пробел создает динамическая диспетчеризация. Указатели на функции, рефлексия, внедрение зависимостей, COM-диспетчеризация, сгенерированные прокси, динамический CALL в COBOL и имена программ, составленные из данных, могут скрывать цель. Сканер исходного кода может зафиксировать место диспетчеризации и выражение для выбора цели, но должен создать неразрешенное ребро, а не угадать одно назначение.

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

Для каждого ребра сохраняйте способ разрешения:

• static, если синтаксис и разрешение символов определяют цель.
• configured, если цель названа в манифесте или настройке.
• observed, если цель записана в трассировке исполнения.
• possible, если анализ диспетчеризации дал ограниченное множество.
• unknown, если место вызова существует, но назначение не разрешено.

Не удаляйте неизвестные ребра ради более чистой картинки. Часто это самые полезные элементы документа: они показывают, где при миграции нужна трассировка или разговор с эксплуатацией. Граф со всеми разрешенными вызовами в системе, которая активно применяет рефлексию или конфигурацию, обычно лишь демонстрирует собственную слепоту.

У модели данных три конкурирующие версии

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

Объявленная схема берется из DDL, файлов миграций, сопоставлений ORM, определений записей, copybook, правил проверки и сохраненных в дереве снимков метаданных базы. Она позволяет определить таблицы, столбцы, типы, индексы, объявленные ключи, допустимость NULL и ограничения. Документация PostgreSQL описывает information_schema.columns как переносимое представление сведений о столбцах и отмечает, что специальные типы PostgreSQL в итоге находятся в pg_catalog. Это полезное предупреждение: даже у метаданных базы есть переносимый и зависящий от поставщика слои.

Используемая схема берется из кода. Строки SQL, конструкторы запросов, ввод и вывод файлов, классы доступа к данным, привязки экранов и определения отчетов показывают, какие поля читает или пишет каждая программа. Это представление выявляет таблицы без объявленных внешних ключей, которые постоянно соединяют, а также столбцы из DDL, больше не встречающиеся в коде репозитория.

Подразумеваемая бизнес-модель добавляет смысл: счет принадлежит клиенту, статус C означает закрытие, а пара дат действия задает период полиса. Автоматизация может предложить такие связи на основе имен, соединений, проверок и повторяющихся преобразований. Без глоссария, теста, подтверждения оператора или наблюдаемых данных она не вправе объявлять их фактами.

Полезная выгрузка сохраняет расхождения видимыми:

SELECT table_schema, table_name, column_name, data_type, is_nullable
FROM information_schema.columns
WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
ORDER BY table_schema, table_name, ordinal_position;

Сравните результат со ссылками в репозитории, не выбирая одну сторону как каноническую. Если код выбирает legacy_code, а в снимке схемы такого столбца нет, снимок может быть устаревшим, SQL условным или промышленная схема другой. Если DDL объявляет внешний ключ, которому не следует код, ограничение все равно имеет значение. Расхождение представляет собой находку, а не помеху, которую следует скрыть при объединении.

Происхождение данных на уровне полей требует той же осторожности. Прямые присваивания и именованные преобразования могут подтвердить ребро происхождения. Хранимая процедура, вызванная через общий шлюз, макрос электронной таблицы или отредактированный оператором экспорт разрывают цепочку. Отметьте разрыв. Не рисуйте сплошную стрелку через отсутствующие свидетельства.

Пакетные зависимости находятся за пределами JCL

Из репозитория можно вывести значительную часть пакетного графа, но JCL или скрипты редко содержат полное промышленное расписание. Они показывают программы, шаги, процедуры, наборы данных, ветвление по кодам возврата и явную отправку заданий. Календари, правила предшествования, ресурсы, переопределения и действия при восстановлении часто находятся в базе планировщика или эксплуатационной конфигурации.

Документация IBM Workload Scheduler описывает предшественников и последователей заданий, в том числе условия по статусу или коду возврата. В документации репозитория JCL также сказано, что планировщик хранит копию JCL для заданий, отправленных в текущем плане. Эти факты показывают важную границу: отправленный JCL является артефактом исполнения, а текущее состояние оркестрации хранит план. Git-репозиторий только с одной стороной не может доказать весь граф зависимостей.

Извлекайте из репозитория как минимум четыре класса ребер: порядок шагов, исполнение программ, поток данных и явное условие. Ребро «производитель-потребитель», выведенное из записи набора данных одним заданием и чтения другим, должно оставаться выведенным. Имена наборов данных могут зависеть от поколения, быть символическими, переопределяться при отправке или использоваться совместно по причинам, не связанным с порядком.

Представляйте результат в форме, где есть место отсутствующим источникам:

job: CLOSE_AR
steps:
  - exec: EXTRACT_AR
    writes: [AR.CLOSE.GDG(+1)]
  - exec: POST_AR
    when: EXTRACT_AR.RC <= 4
external_predecessors:
  - name: LOAD_RATES
    source: scheduler_export
unresolved:
  - "Symbolic HLQ is supplied by the submission profile"

Последнее поле входит в документацию и не требует оправданий. Оно сообщает команде миграции, какой артефакт нужно запросить следующим.

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

Свидетельства исполнения меняют ответ

Статическое извлечение описывает возможности репозитория. Свидетельства исполнения показывают действия выбранных запусков. Эти представления нельзя подменять друг другом.

Записанные трассировки, журналы команд базы данных, истории заданий, метаданные сообщений, каталоги файлов и промышленный трафик могут подтвердить динамические цели и расставить приоритеты путей. Они способны показать, что на протяжении периода сбора настраиваемый диспетчер выбрал три программы из двадцати возможных. Они не доказывают, что остальные семнадцать мертвы. Отсутствие в трассировке означает «не наблюдалось в этой выборке», а не «недостижимо».

Лучшая документация хранит статические и наблюдаемые ребра раздельно, а затем показывает их пересечение и различия. Рассмотрим место вызова с настроенным списком целей RATEA, RATEB и RATEC. Трассировка закрытия месяца видит RATEA и RATEC. Правильная запись сохраняет все три возможные цели, отмечает две как наблюдаемые и фиксирует период и среду сбора. Удаление RATEB из графа превратило бы ограниченное свидетельство в ложное утверждение.

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

Здесь анализ репозитория перестает быть просто более красивым индексом. Статический граф показывает места для датчиков. Трассировки указывают на неразрешенные ребра, требующие внимания. Различия между старым и новым исполнением раскрывают недокументированное поведение, и эти находки можно вернуть в хранилище свидетельств.

Нельзя позволять слою исполнения стирать статическую основу. Редкие квартальные задания, обработчики ошибок, регуляторные выгрузки и аварийные процедуры могут не попасть в обычную запись. Команды нередко считают их мертвым кодом из-за молчания стандартной трассировки, а затем узнают назначение во время единственного события, когда они запускаются.

Сгенерированному тексту нужны ссылки и срок действия

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

Коммит репозитория задает дату действия документа. Если основная ветка меняется, сгенерированный документ устаревает, даже когда его текст по-прежнему кажется правдоподобным. Перегенерируйте его в системе непрерывной интеграции или четко укажите описываемый коммит. Я предпочитаю падение проверки свежести молчаливой смеси старых диаграмм с новым кодом.

Утверждения требуют разных форм ссылок. Структурное утверждение может ссылаться на строки исходного кода. Утверждение о выполнении должно ссылаться на набор трассировок или выгрузку истории заданий вместе с окном наблюдения. Бизнес-определение должно ссылаться на утвержденный глоссарий, правило, тест или названного проверяющего. Если ссылки нет, обозначьте формулировку как вопрос или вывод.

Используйте небольшой журнал проверки, а не прячьте неопределенность в тексте:

ID       CLAIM                                  CLASS       EVIDENCE
DOC-041  POSTINV writes AR_LEDGER               observed    post_invoice.cbl:88
DOC-042  AR_LEDGER is the accounting system     inferred    table name, 6 writers
DOC-043  CLOSE_AR may be safely restarted       unresolved  no recovery rule found

Форма результата важна, поскольку влияет на поведение проверяющего. Если все три утверждения превратить в гладкие абзацы, читатели склонны принимать их вместе. Журнал не дает слабому утверждению притвориться сильным.

Срок действия должен быть избирательным. Реестр модулей можно обновлять при каждом слиянии. Подтвержденный оператором бизнес-смысл должен сохраняться до изменения свидетельства, а система обязана хранить подтверждение и источник. Утверждение о выполнении устаревает, когда окно наблюдения перестает отражать текущее использование. Единая отметка «обновлено» не передает эти различия.

Репозиториям с разными языками нужна общая модель свидетельств

Один парсер не способен документировать систему на COBOL, JCL, PL/SQL, shell, Java и макросах электронных таблиц. Каждому языку нужен свой анализатор, который понимает объявления и правила разрешения, а объединенному результату нужен общий словарь единиц, точек входа, информационных ресурсов и ребер.

Текстовый поиск по-прежнему полезен, но он должен находить кандидатов, а не утверждать связи. Поиск имени таблицы может обнаружить встроенный SQL, комментарии, скопированные определения, тестовые данные и несвязанные поля с таким же написанием. Анализатор языка способен классифицировать часть совпадений. Последующий этап разрешения может связать вызов с объявлением при правильной конфигурации сборки.

Нормализуйте идентификаторы, не стирая исходные имена. POSTINV, имя исходного файла, имя загрузочного модуля и операция планировщика могут обозначать один исполняемый файл на разных этапах. Сохраняйте каждый идентификатор и добавляйте подтвержденную связь псевдонима. Если псевдоним основан только на правиле именования, помечайте его как выведенный. Слишком раннее слияние идентификаторов создает ложные ребра, которые потом трудно распутать.

Связи между языками обычно проявляются в протоколах и артефактах, а не в символах. Задание COBOL пишет простой файл, который читает скрипт Perl. Клиент VB6 вызывает интерфейс COM, реализованный на Delphi. Хранимая процедура пишет в таблицу очереди, которую опрашивает сервис. Моделируйте файл, интерфейс, таблицу или сообщение как самостоятельный узел. Прямая связь двух программ скрыла бы контракт, который действительно их связывает.

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

Большие репозитории добавляют проблему масштаба, а не новую проблему истины. Разбирайте файлы постепенно, кешируйте результаты по содержимому и пересчитывайте затронутые ребра при изменении объявлений или конфигурации. Не сокращайте охват выборкой каталогов, называя результат картой системы. Дерево с миллионом строк можно обработать по частям, но ссылки через границы все равно нужно разрешать по полному реестру.

Выборочная проверка может быть тщательной

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

Начните с примеров для парсеров. Дайте анализатору каждого языка небольшие случаи прямых вызовов, псевдонимов, условной компиляции, динамической диспетчеризации, включений, неверного ввода и комментариев с похожим на код текстом. Проверяйте как обязательные ребра, так и соблазнительные ложные ребра, которые он должен отвергнуть. Сохраняйте сокращенные реальные сбои как регрессионные тесты.

После извлечения запустите инварианты для всего репозитория. Каждый указанный файл и строка должны существовать в анализируемом коммите. У каждой разрешенной цели вызова должно быть объявление или явный внешний идентификатор. Каждый член модуля должен присутствовать в реестре. Каждый тип ребра должен использовать разрешенные типы источника и назначения. Такие проверки не доказывают смысл, но находят сломанные соединения и устаревшие адреса раньше проверяющего.

Затем выбирайте материал для проверки неравномерно. Изучите все неизвестные ребра у важных точек входа, все записи через границы модулей, все условия планировщика и случайную долю обычных статических вызовов. Проверяйте и отрицательное пространство: выберите известные динамические механизмы и убедитесь, что документ показывает их неопределенность. Оценка точности только по простым прямым вызовам поощряет неверно устроенную систему.

Краткий приемочный отчет может содержать полезные числа, не превращая их в оценку качества:

Analyzed commit: 7c41e2f
Parsed files: 18,442 of 18,517 discovered
Skipped files: 75 (list attached to the evidence store)
Resolved call edges: 91,208
Unknown dispatch sites: 613
Broken citations: 0
Scheduler sources: repository JCL only; current-plan export absent

Числа показывают форму результата, а не эталон. Важны знаменатель, список пропущенных файлов и отсутствующий источник планировщика. Отчет «проанализировано 18 442 файла» без упоминания 75 пропущенных позволяет отказавшему парсеру раствориться в большом итоге.

Исправления по итогам проверки должны обновлять правила или свидетельства, а не только показанный абзац. Если проверяющий нашел ложный псевдоним, добавьте ограничение, предотвращающее слияние в следующий раз. Если оператор подтвердил бизнес-определение, сохраните подтверждение как отдельный источник. Иначе повторная генерация аккуратно воссоздаст каждую уже исправленную ошибку.

Доверие заканчивается на динамических и человеческих границах

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

Это утверждение можно превратить в контрольный список:

1. Разрешите каждый упомянутый артефакт. Найдите подключаемые файлы, созданные исходники, библиотеки процедур, управляющие карты, схемы и манифесты развертывания. Зафиксируйте все отсутствующее.
2. Сравните реальную сборку со структурой репозитория. Запишите флаги компилятора, условные символы, шаги генерации кода и точный состав единиц развертывания.
3. Наложите свидетельства исполнения, не считая их исчерпывающими. Сохраняйте период выборки и среду рядом с каждым наблюдаемым ребром.
4. Спросите эксплуатацию о перезапуске, отсечении, переопределениях и исключительных путях. Эти правила часто хранятся в инструкциях, консолях планировщика или памяти людей.
5. Требуйте именованный источник для бизнес-обозначений. Правдоподобная расшифровка восьмизначного имени поля остается догадкой.

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

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

Практический приемочный тест прост: выберите утверждения случайным образом и пройдите по их ссылкам. Если проверяющие не могут воспроизвести структурные утверждения, система не готова. Если утверждения воспроизводятся, но текст вызывает несогласие, исправьте правило вывода или формулировку, не удаляя извлеченные свидетельства.

Документация должна управлять планом переписывания

Документация репозитория оправдывает затраты, когда меняет порядок, тестирование и объем работ. Карта модулей должна определять независимо заменяемые единицы и узлы общего состояния. Обратный граф вызовов должен раскрывать вызывающие компоненты, которым нужна проверка совместимости. Модель данных должна выявлять споры о владении и скрытую связанность. Пакетный граф должен показывать сроки отсечения и пути восстановления, которые требуется сохранить при переходе к сервисам.

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

Модернизации архитектуры также нужна исходная линия поведения. Пословный перенос каждой старой программы на новый язык сохраняет случайные границы и делает сгенерированные диаграммы знакомыми, но знакомый вид плохо подходит как критерий проектирования. Определяйте совместимость по наблюдаемым точкам входа, контрактам данных, побочным эффектам и ограничениям порядка. Затем проектируйте целевые сервисы вокруг связного владения.

CodeHero применяет это сочетание при переписывании старых систем: платформа читает все дерево с разными языками, а стенд проверки паритета сравнивает замену с записанным промышленным трафиком. Выведенное назначение при этом не становится фактом. Структурное извлечение и свидетельства поведения решают разные задачи, и переписыванию нужна именно такая дисциплина.

Перед утверждением сгенерированного документа потребуйте ответ на конкретный вопрос: какие утверждения изменятся, если завтра появятся выгрузка планировщика, трассировка исполнения или интервью с эксплуатацией? Если документ не может назвать их, он спрятал неопределенность вместо управления ею. Репозиторий способен дать отличную карту, но пустые области должны оставаться видимыми, пока их не заполнят свидетельства.

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