confluence-md-sync 0.8.7 → 0.8.9

package/dist/macros/registry.js

@@ -1,6 +1,6 @@
 import { Markdown } from '../markdown/markdown.js';
 import { unescapeParamValue } from './builder.js';
-import { generateMacroId, structuredMacro } from './xml.js';
+import { stableMacroId, structuredMacro } from './xml.js';
 /**
  * Реестр макросов. Пустой при создании — наполняется плагинами через
  * {@link use} или точечной регистрацией через {@link register}.
@@ -126,7 +126,9 @@ function processMacroType(storage, macroName, renderer) {
         }
         const bodyStart = startIdx + match[0].length;
         const body = storage.substring(bodyStart, endIdx).trim();
-        const macroId = generateMacroId();
+        // Стабильный id от содержимого маркера — иначе он менялся бы на КАЖДЫЙ
+        // рендер (см. stableMacroId), ломая content-hash идемпотентность publish.
+        const macroId = stableMacroId(`${macroName}\u0000${paramStr}\u0000${body}`);
         const macroXhtml = renderer({ params, body, macroId });
         const before = storage.substring(0, startIdx);
         const after = storage.substring(endIdx + endMarker.length);

package/dist/macros/xml.d.ts

@@ -2,8 +2,21 @@
 import type { MacroParam } from './types.js';
 /** Экранирует строку для XML-атрибутов и текстовых узлов. */
 export declare function escapeXmlAttr(s: string): string;
-/** Генерирует UUID для ac:macro-id. */
+/** Генерирует случайный UUID для ac:macro-id (когда стабильность не нужна). */
 export declare function generateMacroId(): string;
+/**
+ * Детерминированный macro-id (UUID-формы) от seed — как правило, от исходного
+ * содержимого маркера (имя+параметры+тело). ВАЖНО для идемпотентности
+ * content-hash: если id генерировать случайно на каждый рендер (см.
+ * {@link generateMacroId}), storage у страницы с любым макросом отличается
+ * при каждой публикации, даже когда исходный markdown не менялся — hash
+ * никогда не совпадает, и publish принудительно обновляет страницу заново
+ * при каждом прогоне (замечено на проде: 1 изменённый файл → 250+ страниц
+ * «обновились», потому что ~250 из них содержат макрос details/properties).
+ * Стабильный id по содержимому убирает этот псевдо-дрейф: одинаковый маркер
+ * даёт одинаковый storage → hash совпадает → UNCHANGED.
+ */
+export declare function stableMacroId(seed: string): string;
 export interface StructuredMacroOptions {
     /**
      * Macro parameters. `undefined` values are skipped. A key rendered as

package/dist/macros/xml.js

@@ -1,4 +1,5 @@
 /** XML helpers shared by macro renderers. */
+import { createHash } from 'node:crypto';
 /** Экранирует строку для XML-атрибутов и текстовых узлов. */
 export function escapeXmlAttr(s) {
     return s.replace(/[<>&"']/g, (c) => {
@@ -12,7 +13,7 @@ export function escapeXmlAttr(s) {
         }
     });
 }
-/** Генерирует UUID для ac:macro-id. */
+/** Генерирует случайный UUID для ac:macro-id (когда стабильность не нужна). */
 export function generateMacroId() {
     return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
         const r = (Math.random() * 16) | 0;
@@ -20,6 +21,24 @@ export function generateMacroId() {
         return v.toString(16);
     });
 }
+/**
+ * Детерминированный macro-id (UUID-формы) от seed — как правило, от исходного
+ * содержимого маркера (имя+параметры+тело). ВАЖНО для идемпотентности
+ * content-hash: если id генерировать случайно на каждый рендер (см.
+ * {@link generateMacroId}), storage у страницы с любым макросом отличается
+ * при каждой публикации, даже когда исходный markdown не менялся — hash
+ * никогда не совпадает, и publish принудительно обновляет страницу заново
+ * при каждом прогоне (замечено на проде: 1 изменённый файл → 250+ страниц
+ * «обновились», потому что ~250 из них содержат макрос details/properties).
+ * Стабильный id по содержимому убирает этот псевдо-дрейф: одинаковый маркер
+ * даёт одинаковый storage → hash совпадает → UNCHANGED.
+ */
+export function stableMacroId(seed) {
+    const hex = createHash('sha256').update(seed, 'utf-8').digest('hex');
+    const bytes = hex.slice(0, 32);
+    return (`${bytes.slice(0, 8)}-${bytes.slice(8, 12)}-4${bytes.slice(13, 16)}-` +
+        `${'89ab'[parseInt(bytes[16], 16) % 4]}${bytes.slice(17, 20)}-${bytes.slice(20, 32)}`);
+}
 /**
  * Assembles an `<ac:structured-macro>` element. Takes care of parameter
  * escaping, rich vs plain bodies and CDATA safety.

package/dist/markdown/render.d.ts

@@ -43,6 +43,18 @@ export interface RenderStorageOptions {
     fileStyle?: 'url' | 'attachment';
     /** Автопревращение голых URL в ссылки (default: true). */
     linkify?: boolean;
+    /**
+     * Резолвер относительных ссылок на другие md-файлы набора. Для каждой
+     * markdown-ссылки `[text](href)` вызывается с исходным href; если вернул
+     * цель — ссылка публикуется как Confluence page-link (`<ac:link><ri:page>`)
+     * на страницу связанного md (карту file→page строит вызывающий, напр.
+     * docs-studio из манифеста). `null`/`undefined` — ссылка остаётся как есть
+     * (обычная `<a href>`), пригодна для внешних URL и якорей.
+     */
+    linkResolver?: (href: string) => {
+        title: string;
+        space?: string;
+    } | null;
 }
 export declare class MissingAttachmentUrlError extends Error {
     constructor(message: string);

package/dist/markdown/render.js

@@ -116,6 +116,28 @@ export function renderToStorage(markdown, urls, opts = {}) {
     // markdown-it сквозь себя не пропускает). Fence рендерится в экранированный
     // <pre><code>; здесь разэкранируем содержимое обратно в живую разметку.
     html = html.replace(/<pre><code class="language-confluence-storage">([\s\S]*?)<\/code><\/pre>\n?/g, (_full, escaped) => unescapeHtml(escaped.replace(/\n$/, '')) + '\n');
+    // Ссылки на связанные md → Confluence page-link по резолверу (карта из
+    // манифеста). Только markdown-ссылки (`<a href>` из markdown-it); плейсхолдеры
+    // {{file:}}/{{img:}} рендерятся ниже и сюда ещё не попали. Внешние URL/якоря
+    // резолвер отсекает (возвращает null) — они остаются как есть.
+    if (opts.linkResolver) {
+        const resolve = opts.linkResolver;
+        html = html.replace(/<a href="([^"]*)">([\s\S]*?)<\/a>/g, (full, href, inner) => {
+            const decoded = unescapeHtml(href);
+            if (/^(?:[a-z][a-z0-9+.-]*:|#|\/\/)/i.test(decoded))
+                return full; // http(s):, mailto:, #anchor
+            const target = resolve(decoded);
+            if (!target)
+                return full;
+            const text = unescapeHtml(inner.replace(/<[^>]+>/g, '')).trim();
+            const attrs = [];
+            if (target.space)
+                attrs.push(['space', target.space]);
+            if (text)
+                attrs.push(['text', text]);
+            return renderPageLink(target.title, attrs);
+        });
+    }
     return html.replace(PLACEHOLDER_RE, (_full, kind, rawBody) => {
         const { name, attrs } = parsePlaceholder(String(rawBody));
         if (kind === 'page') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-md-sync",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "Publish Markdown to Confluence (Data Center & Cloud): idempotent page sync, attachment dedup, tables and a pluggable macro system",
   "keywords": [
     "confluence",