kbakaras / cop Goto Github PK

При указании неверного пароля сейчас выводится стектрейс.

Нужно сделать, чтобы выравнивание парсилось опционально.

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

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

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

Необходимо выводить понятную диагностику по описанным выше проверкам.

Если в режиме обновления (update) указан идентификатор обновляемой страницы --page-id и он не найден, нужно обрабатывать ошибку и выводить нормальное сообщение об ошибке вместо распечатки стека.

При конвертации phrase-нод для типа выделения monospaced, нужно использовать тег code вместо pre.
Тег code входит в phrasing-категорию HTML, а `pre' лишь только во flow.
См. Content categories.

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

Настроить сборку и публикацию docker-образа через Actions.

Сейчас это поле никак не используется. Можно его просто удалить, чтобы быстро решить проблему.

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

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

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

• добавленные файлы,
• обновлённые файлы,
• файлы, которые более не используются текущей версией страницы.

При использовании в документе include с относительными путями, напр.

$ cat some-module/README.adoc
...
[source%nowrap,bash]
----
include::../project-all/scripts/partitions.sh[]
----

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

$ docker run -it -v $PWD:/docs kbakaras/cop:v0.1.1 -l ... -p ... -s ... -b ... publish -f /docs/some-module/README.adoc

[main] INFO ru.kbakaras.cop.PublishCommand - Running asciidoctor conversion of '/docs/some-module/README.adoc'
Jul 12, 2022 9:46:54 AM uri:classloader:/gems/asciidoctor-2.0.17/lib/asciidoctor/reader.rb preprocess_include_directive
SEVERE: <stdin>: line 38: include file not found: /project-all/scripts/partitions.sh

Если явно выставить WORKDIR в место, где лежит README.adoc, все работает нормально:

$ docker run -it -v $PWD:/docs -w /docs/some-module kbakaras/cop:v0.1.1 -l ... -p ... -s ... -b ... publish -f /docs/some-module/README.adoc
<OK>

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

Для этого режима понадобится отдельное пространство в Confluence с ограниченным доступом, чтобы его содержимое не отображалось в поиске пользователей.

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

См. также #61.

При конвертации не учитывается стиль ячейки таблицы. Ячейки со сложным форматированием воспринимаются как ячейки с простым текстовым содержимым.

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

Нужно выполнить поиск на Confluence страницы по заголовку и, в зависимости от результата сообщить о возможности обновления/публикации. Также можно проанализировать изображения и вложения и вывести по ним прогноз, что именно будет предпринято в случае публикации/обновления страницы.

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

Нужно вернуться к использованию jsoup для пост-обработки результата перед публикацией, а во время сверки использовать htmlcleaner.

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

Из-за этого эффекта при публикации возникает расхождение между публикуемым содержимым и тем, что возвращает Confluence после своей обработки. Нужно сделать так, чтобы публикуемое содержимое было максимально приведено к тому, виду, в который его адаптирует Confluence.

Также обновить Java до 11 версии.

Если заголовок страницы имеет неправильный уровень (== Foo вместо = Foo), после рендеринга на его месте оказывается null (текстом), хотя сам рендеринг проходит без ошибок.

Было бы более уместным (если возможно) выдавать в подобных случаях ошибку (или хотя бы предупреждение).

Вместо русскоязычных имён файлов на сервер Confluence приходят "вопросики".

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

После успешной публикации утилита удаляет опубликованный документ. Удаление осуществляется в два запроса к API: сначала документ переносится в корзину (trash), а потом окончательно удаляется из корзины (purge). Вот на втором шаге и возникают иногда ошибки: вместо успешного удаления (204) Confluence отвечает ошибкой (500). Вероятно, при слишком быстром последовательном выполнении шагов trash-purge не успевают обновиться какие-нибудь индексы.

Предлагаемое решение: при получении ошибки на шаге purge предпринять несколько повторных попыток, а если и они окажутся неуспешными, ограничиться выводом предупреждения в лог сборки.

Тег ri:version-at-save необходим, чтобы в истории страницы появлялась запись даже в том случае, если изменился только файл вложения. Необходимо добавить логику установки этого флага при обработке вложений. Это необходимо ещё и для того, чтобы проверка на совпадение содержимого страницы при сохранении отрабатывала корректно.

Необходимо различать глобальные ссылки и аттачменты. По аттачментам нужно делать загрузку содержимого файлов в аттачменты Confluence.

Нужно добавить функциональность по обработке ссылок на локальные файлы. Файлы нужно публиковать на Confluence как аттачменты, логика аналогична работе с картинками.

Нужно реализовать две раздельные подкоманды для первичной публикации и для обновления. Также необходимо добавить параметр, позволяющий задать идентификатор родительской страницы. В режиме обновления должен появиться параметр, задающий идентификатор данной (обновляемой) страницы.

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

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

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

При наличии в документе ссылки на директорию, напр.

* `test` -- имя link:kustomize/overlays[оверлея (конфигурации)],

попытка отрендерить документ падает с ошибкой:

[main] ERROR ru.kbakaras.cop.PublishCommand - Asciidoctor conversion of '/docs/README.adoc' failed
    java.io.FileNotFoundException: /docs/kustomize/overlays (Is a directory)

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

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

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

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