confluence-md-sync 0.1.1

package/dist/pages/page.js

@@ -0,0 +1,234 @@
+/**
+ * Объектная модель для работы со страницами и таблицами Confluence.
+ */
+import { findTable, findTableInMacro, renderMarkdownTable } from './tables.js';
+import { Attachment, toAttachmentVersion } from '../attachments/attachment.js';
+/**
+ * Представляет страницу Confluence.
+ */
+export class Page {
+    id;
+    title;
+    storage;
+    client;
+    constructor(id, title, storage, client) {
+        this.id = id;
+        this.title = title;
+        this.storage = storage;
+        this.client = client;
+    }
+    /** Сырой storage-контент страницы. */
+    getStorage() {
+        return this.storage;
+    }
+    /**
+     * Скачивает аттач страницы по имени файла. Возвращает сырые байты.
+     * Текстовая декодировка — через {@link getAttachmentText}.
+     */
+    async getAttachment(filename) {
+        const list = await this.client.listAttachments(this.id, filename);
+        const att = list.find((a) => a.title === filename);
+        if (!att)
+            throw new Error(`Attachment '${filename}' not found on page ${this.id}`);
+        const path = att._links?.download;
+        if (!path)
+            throw new Error(`Attachment '${filename}' on page ${this.id} has no download link`);
+        return this.client.downloadAttachment(path);
+    }
+    /** Скачивает аттач и декодирует как текст (по умолчанию utf-8). */
+    async getAttachmentText(filename, encoding = 'utf-8') {
+        const buf = await this.getAttachment(filename);
+        return buf.toString(encoding);
+    }
+    /** Список аттачей страницы с историей версий (versions заполнены). */
+    async getAttachments() {
+        const list = await this.client.listAttachments(this.id);
+        return Promise.all(list.map(async (a) => {
+            const raw = await this.client.getAttachmentVersions(a.id);
+            const versions = raw
+                .map(toAttachmentVersion)
+                .sort((x, y) => y.version - x.version);
+            const downloadUrl = a._links?.download
+                ? this.client.absoluteUrl(a._links.download)
+                : this.client.absoluteUrl(`/download/attachments/${this.id}/${encodeURIComponent(a.title)}`);
+            return new Attachment(a.id, this.id, a.title, a.version?.number ?? 0, downloadUrl, versions);
+        }));
+    }
+    /**
+     * Удаляет у всех аттачей страницы старые версии, оставляя только последнюю
+     * (max по номеру). Полезно для регулярно перезаписываемых файлов (CSV),
+     * которые иначе копят десятки версий. Возвращает число удалённых версий.
+     */
+    async removeOldAttachmentVersions() {
+        const attachments = await this.getAttachments();
+        let removed = 0;
+        for (const att of attachments) {
+            if (att.versions.length <= 1)
+                continue;
+            const latest = Math.max(...att.versions.map((v) => v.version));
+            for (const v of att.versions) {
+                if (v.version >= latest)
+                    continue;
+                try {
+                    await this.client.removeAttachmentVersion(this.id, att.title, v.version);
+                    removed++;
+                }
+                catch (err) {
+                    console.warn(`[attachments] не удалось удалить ${att.title} v${v.version}: ${err.message}`);
+                }
+            }
+        }
+        return removed;
+    }
+    /** Лейблы страницы. */
+    async getLabels() {
+        return this.client.getLabels(this.id);
+    }
+    /** Добавляет лейблы (идемпотентно). */
+    async addLabels(labels) {
+        await this.client.addLabels(this.id, labels);
+    }
+    /** Дочерние страницы. */
+    async getChildren() {
+        return this.client.getChildPages(this.id);
+    }
+    /**
+     * Извлекает таблицу со страницы.
+     *
+     * @param target порядковый номер таблицы (0 = первая) или имя
+     *   table-excerpt-макроса, обёрнутого вокруг таблицы (параметр `name`).
+     * @throws если таблица не найдена
+     */
+    getTable(target = 0) {
+        const tableHtml = typeof target === 'string'
+            ? findTableInMacro(this.storage, target)
+            : findTable(this.storage, target);
+        if (!tableHtml) {
+            const desc = typeof target === 'string' ? `macro name="${target}"` : `index ${target}`;
+            throw new Error(`Table not found on page ${this.id} (${desc})`);
+        }
+        return new Table(tableHtml);
+    }
+    /**
+     * Извлекает все таблицы со страницы.
+     */
+    getTables() {
+        const tables = [];
+        let index = 0;
+        while (true) {
+            try {
+                tables.push(this.getTable(index));
+                index++;
+            }
+            catch {
+                break;
+            }
+        }
+        return tables;
+    }
+}
+/**
+ * Представляет таблицу Confluence (извлечённую из HTML storage format).
+ *
+ * Предоставляет методы для преобразования таблицы в разные форматы:
+ * - `toCells()` — массив строк и ячеек
+ * - `toAny()` — массив объектов с заголовками как ключи
+ * - `toType<T>()` — массив типизированных объектов с маппером
+ */
+export class Table {
+    cells;
+    headers;
+    constructor(tableHtml) {
+        this.cells = tableHtml;
+        this.headers = this.cells[0] || [];
+    }
+    /**
+     * Возвращает сырой массив ячеек таблицы.
+     */
+    toCells() {
+        return this.cells;
+    }
+    /**
+     * Возвращает строки таблицы (без заголовков) как массив объектов.
+     *
+     * Ключи объектов — заголовки колонок.
+     * Если есть дублирующиеся заголовки, к имени добавляется порядковый номер.
+     *
+     * @example
+     *   table.toAny() → [
+     *     { 'Таб.№': '14800145', 'ФИО': 'Иванов И.И.', ... },
+     *     { 'Таб.№': '14800146', 'ФИО': 'Петров П.П.', ... },
+     *   ]
+     */
+    toAny() {
+        const headerMap = this.buildHeaderMap();
+        return this.cells.slice(1).map((row) => {
+            const obj = {};
+            row.forEach((cell, i) => {
+                const key = headerMap.get(i) || `[${i}]`;
+                obj[key] = cell;
+            });
+            return obj;
+        });
+    }
+    /**
+     * Преобразует таблицу в массив типизированных объектов.
+     *
+     * @param mapper функция, которая заполняет поля результирующего объекта на основе строки таблицы
+     * @returns массив объектов типа T, заполненный маппером
+     *
+     * @example
+     *   const employees = table.toType<Employee>((row, emp) => {
+     *     emp.tabNumber = row['Таб.№'];
+     *     emp.fio = row['ФИО'];
+     *   });
+     */
+    toType(mapper) {
+        const rows = this.toAny();
+        const results = [];
+        for (const row of rows) {
+            const result = {};
+            mapper(row, result);
+            results.push(result);
+        }
+        return results;
+    }
+    /** Возвращает количество строк (включая заголовок). */
+    get rowCount() {
+        return this.cells.length;
+    }
+    /** Возвращает количество колонок. */
+    get columnCount() {
+        return this.headers.length;
+    }
+    /** Возвращает заголовки колонок. */
+    getHeaders() {
+        return [...this.headers];
+    }
+    /** Возвращает таблицу в Markdown формате для использования с макросами. */
+    toMarkdown() {
+        const items = this.toAny();
+        const columns = this.headers.map((header) => ({
+            header,
+            cell: (item) => item[header] || '',
+        }));
+        return renderMarkdownTable(items, columns);
+    }
+    /** Строит карту заголовков с обработкой дубликатов. */
+    buildHeaderMap() {
+        const map = new Map();
+        const seen = new Map();
+        this.headers.forEach((header, i) => {
+            const normalized = header.toLowerCase();
+            const count = (seen.get(normalized) || 0) + 1;
+            seen.set(normalized, count);
+            if (count === 1) {
+                map.set(i, header);
+            }
+            else {
+                map.set(i, `${header} (${count})`);
+            }
+        });
+        return map;
+    }
+}

package/dist/pages/tables.d.ts

@@ -0,0 +1,72 @@
+import type { ConfluenceConfig } from '../client/config.js';
+import { Markdown } from '../markdown/markdown.js';
+/** Читает таблицу со страницы Confluence (storage format) и возвращает `string[][]`. */
+export declare function readTableFromConfluence(pageId: string, cfg: ConfluenceConfig, tableIndex?: number): Promise<string[][]>;
+/**
+ * Ищет таблицу в Confluence storage XHTML по индексу (первая таблица = 0).
+ * Возвращает `string[][]` с ячейками таблицы или null, если не найдена.
+ */
+export declare function findTable(storage: string, index?: number): string[][] | null;
+/**
+ * Ищет первую таблицу внутри table-excerpt-макроса с заданным значением
+ * параметра `name`. Возвращает ячейки или null, если такого макроса
+ * (или таблицы внутри него) нет.
+ */
+export declare function findTableInMacro(storage: string, name: string): string[][] | null;
+/**
+ * Парсит Confluence storage XHTML, извлекает её таблицу и возвращает
+ * её ячейки как `string[][]` (где каждый элемент уже декодирован из HTML).
+ */
+export declare function parseHtmlTable(storage: string): string[][];
+/**
+ * Декодирует ячейку HTML-таблицы: удаляет теги, декодирует сущности,
+ * сжимает пробелы, триммирует. Подходит для использования в парсинге
+ * storage format из Confluence.
+ *
+ * Порядок декодирования важен: `&amp;` обрабатывается ПОСЛЕДНИМ, чтобы
+ * не разрушить уже декодированные сущности типа `&lt;`.
+ */
+export declare function decodeHtmlCell(html: string): string;
+/**
+ * Читает таблицу из Confluence и преобразует её в типизированный массив.
+ * Первая строка таблицы считается заголовками.
+ *
+ * @param pageId ID страницы Confluence
+ * @param cfg конфиг Confluence
+ * @param mapRow функция, которая преобразует (строка: string[], заголовки: string[]) → T
+ * @param tableIndex индекс таблицы на странице (0 = первая)
+ * @returns типизированный массив строк таблицы (без заголовков)
+ * @throws если таблица пустая или содержит только заголовки
+ */
+export declare function readAndMapTable<T>(pageId: string, cfg: ConfluenceConfig, mapRow: (row: string[], headers: string[]) => T, tableIndex?: number): Promise<T[]>;
+export type ColumnAlign = 'left' | 'right' | 'center';
+export interface TableColumn<T> {
+    header: string;
+    cell: (item: T) => string;
+    /** Выравнивание колонки в опубликованной таблице. По умолчанию — left. */
+    align?: ColumnAlign;
+}
+/**
+ * Рендерит типизированный массив в Markdown-таблицу на основе описания
+ * колонок. Каждая колонка задаёт заголовок, функцию извлечения значения
+ * и опциональное выравнивание. Выравнивание транслируется markdown-it'ом
+ * в `style="text-align: right|center|left"` на <th>/<td>, что Confluence
+ * сохраняет в storage.
+ *
+ * @param items массив элементов; если пусто, возвращается сообщение «нет данных»
+ * @param columns описание колонок; не может быть пусто
+ * @throws если columns пусто
+ * @example
+ *   interface Row { name: string; hours: number; }
+ *   const cols: TableColumn<Row>[] = [
+ *     { header: 'Имя',  cell: (r) => r.name },
+ *     { header: 'Часы', cell: (r) => r.hours.toFixed(2), align: 'right' },
+ *   ];
+ *   const md = renderMarkdownTable(rows, cols);
+ */
+export declare function renderMarkdownTable<T>(items: T[], columns: Array<TableColumn<T>>): Markdown;
+/**
+ * Экранирует спецсимволы для использования в ячейке Markdown-таблицы:
+ * заменяет `|` на `\|`, переносы на пробелы.
+ */
+export declare function escapeMdTableCell(s: string): string;

package/dist/pages/tables.js

@@ -0,0 +1,163 @@
+import { ConfluenceClient } from '../client/client.js';
+import { Markdown } from '../markdown/markdown.js';
+/** Читает таблицу со страницы Confluence (storage format) и возвращает `string[][]`. */
+export async function readTableFromConfluence(pageId, cfg, tableIndex = 0) {
+    const client = new ConfluenceClient(cfg);
+    const { storage } = await client.getPageStorage(pageId);
+    const table = findTable(storage, tableIndex);
+    if (!table) {
+        const tableCount = (storage.match(/<table/g) || []).length;
+        throw new Error(tableCount === 0
+            ? `readTableFromConfluence(${pageId}): no tables found on page`
+            : `readTableFromConfluence(${pageId}): table ${tableIndex} not found (page has ${tableCount} table(s))`);
+    }
+    return table;
+}
+/**
+ * Ищет таблицу в Confluence storage XHTML по индексу (первая таблица = 0).
+ * Возвращает `string[][]` с ячейками таблицы или null, если не найдена.
+ */
+export function findTable(storage, index = 0) {
+    let tableIdx = 0;
+    for (const tableMatch of storage.matchAll(/<table[^>]*>([\s\S]*?)<\/table>/g)) {
+        if (tableIdx === index) {
+            return parseHtmlTable(tableMatch[1]);
+        }
+        tableIdx++;
+    }
+    return null;
+}
+/**
+ * Ищет первую таблицу внутри table-excerpt-макроса с заданным значением
+ * параметра `name`. Возвращает ячейки или null, если такого макроса
+ * (или таблицы внутри него) нет.
+ */
+export function findTableInMacro(storage, name) {
+    const macroRe = /<ac:structured-macro[^>]*ac:name="table-excerpt"[^>]*>([\s\S]*?)<\/ac:structured-macro>/g;
+    for (const macroMatch of storage.matchAll(macroRe)) {
+        const inner = macroMatch[1];
+        const nameRe = /<ac:parameter\s+ac:name="name">([\s\S]*?)<\/ac:parameter>/;
+        const nameMatch = inner.match(nameRe);
+        if (!nameMatch)
+            continue;
+        if (decodeHtmlCell(nameMatch[1]) !== name)
+            continue;
+        const tableMatch = inner.match(/<table[^>]*>([\s\S]*?)<\/table>/);
+        if (!tableMatch)
+            return null;
+        return parseHtmlTable(tableMatch[1]);
+    }
+    return null;
+}
+/**
+ * Парсит Confluence storage XHTML, извлекает её таблицу и возвращает
+ * её ячейки как `string[][]` (где каждый элемент уже декодирован из HTML).
+ */
+export function parseHtmlTable(storage) {
+    const rows = [];
+    for (const tr of storage.matchAll(/<tr[^>]*>([\s\S]*?)<\/tr>/g)) {
+        const cells = [];
+        for (const cell of tr[1].matchAll(/<(t[hd])[^>]*>([\s\S]*?)<\/\1>/g)) {
+            cells.push(decodeHtmlCell(cell[2]));
+        }
+        if (cells.length > 0)
+            rows.push(cells);
+    }
+    return rows;
+}
+/**
+ * Декодирует ячейку HTML-таблицы: удаляет теги, декодирует сущности,
+ * сжимает пробелы, триммирует. Подходит для использования в парсинге
+ * storage format из Confluence.
+ *
+ * Порядок декодирования важен: `&amp;` обрабатывается ПОСЛЕДНИМ, чтобы
+ * не разрушить уже декодированные сущности типа `&lt;`.
+ */
+export function decodeHtmlCell(html) {
+    return html
+        .replace(/<br\s*\/?>/gi, ' ')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Читает таблицу из Confluence и преобразует её в типизированный массив.
+ * Первая строка таблицы считается заголовками.
+ *
+ * @param pageId ID страницы Confluence
+ * @param cfg конфиг Confluence
+ * @param mapRow функция, которая преобразует (строка: string[], заголовки: string[]) → T
+ * @param tableIndex индекс таблицы на странице (0 = первая)
+ * @returns типизированный массив строк таблицы (без заголовков)
+ * @throws если таблица пустая или содержит только заголовки
+ */
+export async function readAndMapTable(pageId, cfg, mapRow, tableIndex = 0) {
+    const rows = await readTableFromConfluence(pageId, cfg, tableIndex);
+    if (rows.length === 0) {
+        throw new Error(`readAndMapTable(${pageId}): table ${tableIndex} is empty`);
+    }
+    const headers = rows[0];
+    if (headers.length === 0) {
+        throw new Error(`readAndMapTable(${pageId}): table ${tableIndex} has no columns`);
+    }
+    if (rows.length === 1) {
+        console.warn(`[readAndMapTable] ${pageId}: table ${tableIndex} contains only headers, no data rows`);
+        return [];
+    }
+    return rows.slice(1).map((row) => mapRow(row, headers));
+}
+/**
+ * Рендерит типизированный массив в Markdown-таблицу на основе описания
+ * колонок. Каждая колонка задаёт заголовок, функцию извлечения значения
+ * и опциональное выравнивание. Выравнивание транслируется markdown-it'ом
+ * в `style="text-align: right|center|left"` на <th>/<td>, что Confluence
+ * сохраняет в storage.
+ *
+ * @param items массив элементов; если пусто, возвращается сообщение «нет данных»
+ * @param columns описание колонок; не может быть пусто
+ * @throws если columns пусто
+ * @example
+ *   interface Row { name: string; hours: number; }
+ *   const cols: TableColumn<Row>[] = [
+ *     { header: 'Имя',  cell: (r) => r.name },
+ *     { header: 'Часы', cell: (r) => r.hours.toFixed(2), align: 'right' },
+ *   ];
+ *   const md = renderMarkdownTable(rows, cols);
+ */
+export function renderMarkdownTable(items, columns) {
+    if (columns.length === 0) {
+        throw new Error('renderMarkdownTable: columns cannot be empty');
+    }
+    if (items.length === 0)
+        return new Markdown('_(нет данных)_');
+    const header = columns.map((c) => escapeMdTableCell(c.header));
+    const sep = columns.map((c) => alignSeparator(c.align));
+    const body = items.map((item) => columns.map((c) => escapeMdTableCell(c.cell(item))));
+    const content = [
+        `| ${header.join(' | ')} |`,
+        `| ${sep.join(' | ')} |`,
+        ...body.map((r) => `| ${r.join(' | ')} |`),
+    ].join('\n');
+    return new Markdown(content);
+}
+function alignSeparator(align) {
+    switch (align) {
+        case 'right': return '---:';
+        case 'center': return ':---:';
+        case 'left': return ':---';
+        default: return '---';
+    }
+}
+/**
+ * Экранирует спецсимволы для использования в ячейке Markdown-таблицы:
+ * заменяет `|` на `\|`, переносы на пробелы.
+ */
+export function escapeMdTableCell(s) {
+    return s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}

package/dist/publish/publish.d.ts

@@ -0,0 +1,67 @@
+import type { ConfluenceConfig } from '../client/config.js';
+import type { MacroRegistry } from '../macros/registry.js';
+import { Markdown } from '../markdown/markdown.js';
+export interface TableData {
+    name: string;
+    markdown: Markdown | string;
+}
+export interface PublishPageOptions {
+    /** Известный ID страницы. Альтернатива — spaceKey + title. */
+    pageId?: string;
+    /**
+     * Space key для поиска/создания страницы по title, когда pageId неизвестен.
+     * Если страницы с таким title в space нет и createIfMissing !== false,
+     * она будет создана (опционально под parentPageId).
+     */
+    spaceKey?: string;
+    /** Путь к markdown-файлу. Альтернатива — `markdown` со строкой/объектом. */
+    markdownPath?: string;
+    /** Готовый markdown-контент (вместо markdownPath). */
+    markdown?: Markdown | string;
+    images?: string[];
+    files?: string[];
+    tables?: TableData[];
+    /**
+     * Заголовок страницы. Для существующей страницы — переименование
+     * (по умолчанию сохраняется текущий); для поиска/создания по spaceKey —
+     * обязательный ключ поиска.
+     */
+    title?: string;
+    /** Родитель для создаваемой страницы (только вместе со spaceKey). */
+    parentPageId?: string;
+    /** Создавать ли страницу, если по spaceKey+title не нашлась. Default: true. */
+    createIfMissing?: boolean;
+    /** Лейблы, которые нужно гарантировать на странице. */
+    labels?: string[];
+    /** Комментарий к версии страницы. */
+    versionMessage?: string;
+    /** Свой реестр макросов (default: встроенные core + table-filter). */
+    registry?: MacroRegistry;
+    /**
+     * Ключ content property для хранения content-hash.
+     * Default: 'confluence-md-sync-content-hash'.
+     */
+    hashPropertyKey?: string;
+    /** Рендер и валидация без записи в Confluence. */
+    dryRun?: boolean;
+}
+export interface PublishPageResult {
+    pageId: string;
+    title: string;
+    version: number;
+    attachments: Array<{
+        filename: string;
+        id: string;
+        reused: boolean;
+        url: string;
+    }>;
+    /** false если контент совпал по hash и updatePage не вызывался. */
+    updated: boolean;
+    /** true если страница была создана в этом запуске. */
+    created: boolean;
+    /** Итоговый storage-контент (полезно в dryRun). */
+    storage: string;
+}
+export declare const DEFAULT_HASH_PROPERTY_KEY = "confluence-md-sync-content-hash";
+export declare function computeContentHash(storage: string): string;
+export declare function publishPage(opts: PublishPageOptions, cfg: ConfluenceConfig): Promise<PublishPageResult>;