confluence-md-sync 0.2.1 → 0.4.0

package/dist/export/export-page.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Экспорт страницы Confluence в комплект «markdown + аттачи», пригодный
+ * для обратной публикации через publishPage (render-стиль 'attachment').
+ */
+import type { ConfluenceConfig } from '../client/config.js';
+import type { MacroRegistry } from '../macros/registry.js';
+import { type StorageToMarkdownResult } from './to-markdown.js';
+export interface ExportPageOptions {
+    /**
+     * Точный путь до итогового md-файла. Альтернатива `outDir`. Аттачи (если
+     * включены) кладутся в `attachments/` рядом с этим файлом.
+     */
+    outFile?: string;
+    /**
+     * Каталог для `page.md` и `attachments/`. Используется, если не задан
+     * `outFile`. Если не задан ни тот, ни другой — `./<pageId>`.
+     */
+    outDir?: string;
+    /** Скачивать ли аттачи, на которые ссылается страница. Default: true. */
+    downloadAttachments?: boolean;
+    /**
+     * 'faithful' (default) — round-trippable, с сырым HTML в fallback;
+     * 'readable' — чистый Markdown ценой оформления (round-trip не гарантирован).
+     */
+    mode?: 'faithful' | 'readable';
+    registry?: MacroRegistry;
+}
+export interface ExportPageResult extends StorageToMarkdownResult {
+    pageId: string;
+    title: string;
+    version: number;
+    markdownPath: string;
+    /** Скачанные файлы: имя аттача → локальный путь. */
+    downloaded: Map<string, string>;
+}
+export declare function exportPage(pageId: string, opts: ExportPageOptions, cfg: ConfluenceConfig): Promise<ExportPageResult>;

package/dist/export/export-page.js

@@ -0,0 +1,41 @@
+/**
+ * Экспорт страницы Confluence в комплект «markdown + аттачи», пригодный
+ * для обратной публикации через publishPage (render-стиль 'attachment').
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { ConfluenceClient } from '../client/client.js';
+import { storageToMarkdown } from './to-markdown.js';
+export async function exportPage(pageId, opts, cfg) {
+    const client = new ConfluenceClient(cfg);
+    const page = await client.getPageStorage(pageId);
+    const converted = storageToMarkdown(page.storage, { registry: opts.registry, mode: opts.mode });
+    const markdownPath = opts.outFile ?? join(opts.outDir ?? `./${pageId}`, 'page.md');
+    mkdirSync(dirname(markdownPath), { recursive: true });
+    writeFileSync(markdownPath, converted.markdown);
+    const downloaded = new Map();
+    if (opts.downloadAttachments !== false && converted.attachmentRefs.length > 0) {
+        const dir = join(dirname(markdownPath), 'attachments');
+        mkdirSync(dir, { recursive: true });
+        for (const name of converted.attachmentRefs) {
+            const [att] = await client.listAttachments(pageId, name);
+            if (att === undefined) {
+                console.warn(`[export] attachment '${name}' referenced by the page but not found`);
+                continue;
+            }
+            const link = att._links?.download ?? `/download/attachments/${pageId}/${encodeURIComponent(name)}`;
+            const data = await client.downloadAttachment(link);
+            const path = join(dir, name);
+            writeFileSync(path, data);
+            downloaded.set(name, path);
+        }
+    }
+    return {
+        ...converted,
+        pageId,
+        title: page.title,
+        version: page.version,
+        markdownPath,
+        downloaded,
+    };
+}

package/dist/export/roundtrip.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Round-trip-проверка: storage → markdown → storage′ и каноническое
+ * сравнение (см. canonical.ts — критерий «без потери разметки»).
+ */
+import type { ConfluenceConfig } from '../client/config.js';
+import { type MacroRegistry } from '../macros/registry.js';
+import { type StorageDiff } from './canonical.js';
+import { type StorageToMarkdownResult } from './to-markdown.js';
+export interface RoundTripResult extends StorageToMarkdownResult {
+    /** storage, восстановленный из markdown публикационным конвейером. */
+    regenerated: string;
+    equal: boolean;
+    diffs: StorageDiff[];
+}
+/**
+ * Рендерит markdown из exportPage/storageToMarkdown обратно в storage тем
+ * же конвейером, что publishPage (attachment-стиль ссылок, без linkify).
+ */
+export declare function renderExportedMarkdown(markdown: string, registry?: MacroRegistry): string;
+/** Полный офлайн round-trip для готового storage-фрагмента. */
+export declare function roundTripStorage(storage: string, opts?: {
+    registry?: MacroRegistry;
+}): RoundTripResult;
+/** Round-trip для живой страницы: тянет storage по id и проверяет офлайн. */
+export declare function roundTripPage(pageId: string, cfg: ConfluenceConfig, opts?: {
+    registry?: MacroRegistry;
+}): Promise<RoundTripResult & {
+    title: string;
+    version: number;
+}>;

package/dist/export/roundtrip.js

@@ -0,0 +1,32 @@
+/**
+ * Round-trip-проверка: storage → markdown → storage′ и каноническое
+ * сравнение (см. canonical.ts — критерий «без потери разметки»).
+ */
+import { ConfluenceClient } from '../client/client.js';
+import { processMacros } from '../macros/registry.js';
+import { defaultMacroRegistry } from '../macros/index.js';
+import { renderToStorage } from '../markdown/render.js';
+import { compareStorage } from './canonical.js';
+import { storageToMarkdown } from './to-markdown.js';
+/**
+ * Рендерит markdown из exportPage/storageToMarkdown обратно в storage тем
+ * же конвейером, что publishPage (attachment-стиль ссылок, без linkify).
+ */
+export function renderExportedMarkdown(markdown, registry) {
+    const storage = renderToStorage(markdown, { images: new Map(), files: new Map() }, { imageStyle: 'attachment', fileStyle: 'attachment', linkify: false });
+    return processMacros(storage, registry ?? defaultMacroRegistry).toString();
+}
+/** Полный офлайн round-trip для готового storage-фрагмента. */
+export function roundTripStorage(storage, opts = {}) {
+    const converted = storageToMarkdown(storage, opts);
+    const regenerated = renderExportedMarkdown(converted.markdown, opts.registry);
+    const { equal, diffs } = compareStorage(storage, regenerated);
+    return { ...converted, regenerated, equal, diffs };
+}
+/** Round-trip для живой страницы: тянет storage по id и проверяет офлайн. */
+export async function roundTripPage(pageId, cfg, opts = {}) {
+    const client = new ConfluenceClient(cfg);
+    const page = await client.getPageStorage(pageId);
+    const result = roundTripStorage(page.storage, opts);
+    return { ...result, title: page.title, version: page.version };
+}

package/dist/export/to-markdown.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Конвертация Confluence storage → Markdown. Два режима:
+ *
+ * FAITHFUL (default) — гарантия round-trip. Трёхуровневая политика:
+ *  1. чистый Markdown — заголовки, абзацы, списки, простые таблицы,
+ *     ссылки, картинки-аттачи ({{img:...}}), page-ссылки ({{page:...}});
+ *  2. маркеры макросов <!-- MACRO:start/end --> — для макросов, чей
+ *     рендер восстанавливает исходный XHTML (проверяется на месте:
+ *     маркер прогоняется через render-конвейер и сравнивается канонически);
+ *  3. дословный XHTML — «как есть»: без ac:/ri:-тегов — сырым HTML,
+ *     с ними — fenced-блоком ```confluence-storage.
+ *  Потери исключены по построению; но (3) даёт сырой HTML, который многие
+ *  md-редакторы показывают уродливо.
+ *
+ * READABLE — чистый Markdown ценой оформления. Round-trip НЕ гарантируется:
+ *  теряются цвета/стили спанов, div-обёртки, точная геометрия объединённых
+ *  ячеек; сохраняется смысловая нагрузка (текст, структура). Сложные
+ *  таблицы разворачиваются в GFM (colspan/rowspan → сетка с заполнением,
+ *  блочное содержимое ячеек — во flatten через <br>). Сырой HTML-блок не
+ *  выдаётся никогда.
+ */
+import { type MacroRegistry } from '../macros/registry.js';
+export interface StorageToMarkdownOptions {
+    /** Реестр для проверки маркеров макросов (default: встроенный). */
+    registry?: MacroRegistry;
+    /**
+     * 'faithful' (default) — round-trippable, но с сырым HTML в fallback;
+     * 'readable' — чистый Markdown ценой оформления, без round-trip.
+     */
+    mode?: 'faithful' | 'readable';
+}
+export interface StorageToMarkdownResult {
+    markdown: string;
+    /** Имена аттачей, на которые ссылаются {{img:...}}. */
+    images: string[];
+    /** Имена аттачей, на которые ссылаются {{file:...}}. */
+    files: string[];
+    /** Все имена аттачей, упомянутые где-либо (включая fenced-блоки). */
+    attachmentRefs: string[];
+    stats: {
+        markers: number;
+        fenced: number;
+        rawHtml: number;
+        /** readable-режим: сколько узлов конвертировано с потерей оформления. */
+        lossy: number;
+    };
+}
+/** Конвертирует storage-фрагмент страницы в Markdown. */
+export declare function storageToMarkdown(storage: string, opts?: StorageToMarkdownOptions): StorageToMarkdownResult;