arc-1 1.1.2 → 1.3.0

package/dist/adt/ddic-xml.js

@@ -37,7 +37,7 @@ export function normalizeSrvbBindingType(input) {
         category = '0';
     return { type: 'ODATA', odataVersion, category };
 }
-const DTEL_MAX_LABEL_LENGTHS = {
+export const DTEL_MAX_LABEL_LENGTHS = {
     short: 10,
     medium: 20,
     long: 40,
@@ -116,7 +116,10 @@ function formatLength(value, width) {
     }
     return ''.padStart(width, '0');
 }
-function formatLabelLength(label, maxLength) {
+function formatLabelLength(label, maxLength, explicitLength) {
+    if (explicitLength !== undefined && explicitLength !== null && String(explicitLength).trim() !== '') {
+        return formatLength(explicitLength, 2);
+    }
     if (!label)
         return String(maxLength).padStart(2, '0');
     return String(Math.min(label.length, maxLength)).padStart(2, '0');
@@ -326,25 +329,25 @@ export function buildDataElementXml(params) {
     <dtel:dataTypeLength>${formatLength(params.length, 6)}</dtel:dataTypeLength>
     <dtel:dataTypeDecimals>${formatLength(params.decimals, 6)}</dtel:dataTypeDecimals>
     <dtel:shortFieldLabel>${escapeXmlAttr(shortLabel)}</dtel:shortFieldLabel>
-    <dtel:shortFieldLength>${formatLabelLength(shortLabel, DTEL_MAX_LABEL_LENGTHS.short)}</dtel:shortFieldLength>
+    <dtel:shortFieldLength>${formatLabelLength(shortLabel, DTEL_MAX_LABEL_LENGTHS.short, params.shortLength)}</dtel:shortFieldLength>
     <dtel:shortFieldMaxLength>${String(DTEL_MAX_LABEL_LENGTHS.short).padStart(2, '0')}</dtel:shortFieldMaxLength>
     <dtel:mediumFieldLabel>${escapeXmlAttr(mediumLabel)}</dtel:mediumFieldLabel>
-    <dtel:mediumFieldLength>${formatLabelLength(mediumLabel, DTEL_MAX_LABEL_LENGTHS.medium)}</dtel:mediumFieldLength>
+    <dtel:mediumFieldLength>${formatLabelLength(mediumLabel, DTEL_MAX_LABEL_LENGTHS.medium, params.mediumLength)}</dtel:mediumFieldLength>
     <dtel:mediumFieldMaxLength>${DTEL_MAX_LABEL_LENGTHS.medium}</dtel:mediumFieldMaxLength>
     <dtel:longFieldLabel>${escapeXmlAttr(longLabel)}</dtel:longFieldLabel>
-    <dtel:longFieldLength>${formatLabelLength(longLabel, DTEL_MAX_LABEL_LENGTHS.long)}</dtel:longFieldLength>
+    <dtel:longFieldLength>${formatLabelLength(longLabel, DTEL_MAX_LABEL_LENGTHS.long, params.longLength)}</dtel:longFieldLength>
     <dtel:longFieldMaxLength>${DTEL_MAX_LABEL_LENGTHS.long}</dtel:longFieldMaxLength>
     <dtel:headingFieldLabel>${escapeXmlAttr(headingLabel)}</dtel:headingFieldLabel>
-    <dtel:headingFieldLength>${formatLabelLength(headingLabel, DTEL_MAX_LABEL_LENGTHS.heading)}</dtel:headingFieldLength>
+    <dtel:headingFieldLength>${formatLabelLength(headingLabel, DTEL_MAX_LABEL_LENGTHS.heading, params.headingLength)}</dtel:headingFieldLength>
     <dtel:headingFieldMaxLength>${DTEL_MAX_LABEL_LENGTHS.heading}</dtel:headingFieldMaxLength>
     <dtel:searchHelp>${escapeXmlAttr(params.searchHelp ?? '')}</dtel:searchHelp>
     <dtel:searchHelpParameter>${escapeXmlAttr(params.searchHelpParameter ?? '')}</dtel:searchHelpParameter>
     <dtel:setGetParameter>${escapeXmlAttr(params.setGetParameter ?? '')}</dtel:setGetParameter>
     <dtel:defaultComponentName>${escapeXmlAttr(params.defaultComponentName ?? '')}</dtel:defaultComponentName>
-    <dtel:deactivateInputHistory>false</dtel:deactivateInputHistory>
+    <dtel:deactivateInputHistory>${boolToXml(params.deactivateInputHistory)}</dtel:deactivateInputHistory>
     <dtel:changeDocument>${boolToXml(params.changeDocument)}</dtel:changeDocument>
-    <dtel:leftToRightDirection>false</dtel:leftToRightDirection>
-    <dtel:deactivateBIDIFiltering>false</dtel:deactivateBIDIFiltering>
+    <dtel:leftToRightDirection>${boolToXml(params.leftToRightDirection)}</dtel:leftToRightDirection>
+    <dtel:deactivateBIDIFiltering>${boolToXml(params.deactivateBIDIFiltering)}</dtel:deactivateBIDIFiltering>
   </dtel:dataElement>
 </blue:wbobj>`;
 }
@@ -427,69 +430,659 @@ export function buildServiceBindingXml(params) {
  * an `<sktd:id>` and a Base64-encoded `<sktd:text>`. We extract all of them
  * and return a combined Markdown document with element headings.
  */
-export function decodeKtdText(envelopeXml) {
+export function decodeKtdText(envelopeXml, options = {}) {
     // Extract all <sktd:element> blocks with their id and text
     const elementPattern = /<sktd:element[^>]*>[\s\S]*?<sktd:id>([^<]*)<\/sktd:id>[\s\S]*?<\/sktd:element>/g;
     const elements = [];
-    let match;
-    while ((match = elementPattern.exec(envelopeXml)) !== null) {
-        const elementBlock = match[0];
-        const id = match[1].trim();
-        const textMatch = elementBlock.match(/<sktd:text[^>]*>([\s\S]*?)<\/sktd:text>/);
-        const base64 = textMatch?.[1]?.trim() ?? '';
-        let decoded = '';
-        if (base64) {
-            try {
-                decoded = Buffer.from(base64, 'base64').toString('utf-8');
-            }
-            catch {
-                decoded = '';
-            }
-        }
-        if (decoded) {
-            elements.push({ id, text: decoded });
-        }
+    for (const match of envelopeXml.matchAll(elementPattern)) {
+        const text = decodeKtdElementText(match[0]);
+        if (text)
+            elements.push({ id: match[1].trim(), text });
     }
     if (elements.length === 0) {
         // Fallback: try extracting a single <sktd:text> without element structure
-        const singleMatch = envelopeXml.match(/<sktd:text[^>]*>([\s\S]*?)<\/sktd:text>/);
-        if (!singleMatch)
-            return '';
-        const base64 = singleMatch[1].trim();
-        if (!base64)
-            return '';
-        try {
-            return Buffer.from(base64, 'base64').toString('utf-8');
+        const text = decodeKtdElementText(envelopeXml) ?? '';
+        return options.routeSafe === false ? text : escapeKtdBodyMetaMarkers(text);
+    }
+    // A lone documented node still needs its routing heading when writable empty siblings
+    // exist. Otherwise appending one of the ids from formatKtdNodeIndex creates a
+    // non-empty preamble that the inverse writer must refuse. A genuinely single-target
+    // document keeps the compact, backwards-compatible bare body.
+    const allElements = findKtdElements(envelopeXml);
+    const documentedId = elements[0]?.id;
+    const hasOtherWritableTarget = allElements.some((element) => element.id && element.id !== documentedId && canWriteKtdLongText(element.xml));
+    if (elements.length === 1 && !hasOtherWritableTarget) {
+        const routes = ktdRoutes(envelopeXml, allElements);
+        if (options.routeSafe === false)
+            return elements[0].text;
+        const routeEscaped = elements[0].id ? escapeKtdBodyRouteHeadings(elements[0].text, routes) : elements[0].text;
+        const escaped = escapeKtdBodyMetaMarkers(routeEscaped);
+        // Keep the backwards-compatible bare body unless escaping exposed a line that the
+        // section parser would otherwise consume as a route. Metadata-marker escapes are
+        // independently reversible on the unaddressed path and need no outer heading.
+        return routeEscaped === elements[0].text ? escaped : `## ${elements[0].id}\n\n${escaped}`;
+    }
+    // Multiple elements: format as structured Markdown with element headings. Escape
+    // body headings that would otherwise be parsed as routing syntax on write. Prefixing
+    // one backslash is reversible even when the stored line already starts with one.
+    const routes = ktdRoutes(envelopeXml, allElements);
+    return elements
+        .map((e) => `## ${e.id}\n\n${options.routeSafe === false ? e.text : escapeKtdBodyMetaMarkers(escapeKtdBodyRouteHeadings(e.text, routes))}`)
+        .join('\n\n');
+}
+/**
+ * Compact index of EVERY writable node of a KTD, documented or not — the only way to learn a
+ * node's address by reading, since `decodeKtdText` renders sections only for nodes that hold
+ * text. Empty string when the document has no writable node.
+ *
+ * Each node is listed by the spelling that resolves back to it: its node name, or its full id
+ * when the name would resolve elsewhere (a BDEF's root-entity node is named like the object
+ * itself, and that name resolves to the root) or is shared by several nodes. Names are grouped
+ * under their <base> and <TYPE> so a 90-node document costs a few lines, not 90 URIs.
+ */
+export function formatKtdNodeIndex(envelopeXml) {
+    const all = findKtdElements(envelopeXml);
+    const routes = ktdRoutes(envelopeXml, all);
+    if (routes.duplicateIds.size > 0) {
+        return (`SAPWrite unavailable: duplicate node ids (${[...routes.duplicateIds].join(', ')}). ` +
+            'The documentation remains readable, but these elements cannot be addressed separately.');
+    }
+    const writable = all.filter((element) => element.id && canWriteKtdLongText(element.xml));
+    if (writable.length === 0)
+        return '';
+    const roots = [];
+    const namesByBaseAndType = new Map();
+    // Listed on their own line, so the tokens above stay exactly what a caller may copy back —
+    // a marker glued onto a name would itself be a heading that resolves to nothing.
+    const empty = [];
+    for (const element of writable) {
+        const id = element.id;
+        const label = addressableKtdRoute(routes, element);
+        if (!elementBase64(element.xml))
+            empty.push(label);
+        const typeAt = id.indexOf('#type=');
+        const nameAt = typeAt < 0 ? -1 : id.indexOf(';name=', typeAt);
+        if (typeAt < 0 || nameAt < 0) {
+            roots.push(label);
+            continue;
         }
-        catch {
-            return '';
+        const base = id.slice(0, typeAt);
+        const type = id.slice(typeAt + '#type='.length, nameAt);
+        const byType = namesByBaseAndType.get(base) ?? new Map();
+        byType.set(type, [...(byType.get(type) ?? []), label]);
+        namesByBaseAndType.set(base, byType);
+    }
+    const lines = [
+        `Nodes: ${writable.length}${empty.length ? ` (${empty.length} with no text yet, listed under "empty")` : ''}. ` +
+            'Address one with a "## <name>" section in SAPWrite "source", or as shortTexts[].node — every name below is ' +
+            'accepted verbatim. An update only touches the nodes it addresses; the rest keep their current text. ' +
+            'For a root-only H2 edit, keep the complete SAPRead context; when only the root has text, you can also omit its H2.',
+    ];
+    for (const root of roots)
+        lines.push(`root: ${root}`);
+    for (const [base, byType] of namesByBaseAndType) {
+        lines.push(`base: ${base}`);
+        for (const [type, names] of byType)
+            lines.push(`${type} (${names.length}): ${names.join(', ')}`);
+    }
+    if (empty.length > 0)
+        lines.push(`empty (${empty.length}): ${empty.join(', ')}`);
+    return lines.join('\n');
+}
+/** Compare in-place rewrites and label changed nodes for create, update, and preview reports. */
+export function summarizeKtdChanges(before, after) {
+    // Positional: a rewrite replaces element blocks in place and never adds or removes one, so
+    // index i is the same node on both sides — even for elements sharing or lacking an id.
+    const previous = findKtdElements(before);
+    const current = findKtdElements(after);
+    // The legacy write fallback can replace one envelope-level text slot without any elements.
+    if (previous.length === 0 && current.length === 0 && decodeKtdElementText(after) !== undefined) {
+        return before === after ? { changed: [], untouched: 1 } : { changed: ['(document body)'], untouched: 0 };
+    }
+    const routes = ktdRoutes(after, current);
+    const changed = [];
+    let untouched = 0;
+    current.forEach((element, index) => {
+        if (previous[index]?.xml === element.xml)
+            untouched += 1;
+        else
+            changed.push(element.id ? addressableKtdRoute(routes, element) : `(element ${index + 1})`);
+    });
+    return { changed, untouched };
+}
+/** The same routing feedback for a preview, an update, or a post-create documentation write. */
+export function formatKtdWriteReport(before, after, report, dryRun = false) {
+    const { changed, untouched } = summarizeKtdChanges(before, after);
+    const changedList = changed.length > 0 ? `:\n${changed.map((node) => `  ${node}`).join('\n')}` : '.';
+    const proseNote = report.proseHeadings.length > 0
+        ? `\nHeadings kept as prose inside their node (not node routes): ${report.proseHeadings.join(', ')}`
+        : '';
+    return (`${dryRun ? 'Would change' : 'Changed'} ${changed.length} node(s); ${untouched} node(s) ` +
+        `${dryRun ? 'would keep' : 'kept'} their current text${changedList}${proseNote}`);
+}
+/**
+ * The spelling a caller can copy back for this node: its name when that name resolves to this
+ * very element, otherwise the full id. Duplicate IDs are display-only; their read context warns
+ * that writes are unavailable.
+ */
+function addressableKtdRoute(routes, element) {
+    const name = ktdNodeNameSpellings(element.id)[0];
+    const candidates = ktdRouteCandidates(routes, name);
+    return candidates.length === 1 && candidates[0] === element ? name : element.id;
+}
+/** Exact transport line separating writable KTD Markdown from ARC-1 read-only context. */
+export const KTD_META_MARKER = '<!-- arc1:ktd-meta — read-only context below; SAPWrite ignores it -->';
+/** A Markdown level-two heading line. Greedy capture avoids quadratic matching on long input. */
+const KTD_HEADING_LINE = /^##[ \t]+(.*)$/m;
+/**
+ * Remove the read-only context that SAPRead appends after `KTD_META_MARKER`.
+ *
+ * A route-safe SAPRead escapes the same line when it belongs to a stored body. When a complete
+ * read contains both that escaped body line and an appended trailer, the final unescaped marker
+ * is therefore the delimiter. Using the final marker also keeps older complete reads lossless if
+ * their body still contains an unescaped occurrence. A heading below the delimiter is refused
+ * because it is most likely a node section appended in the wrong place.
+ */
+export function stripKtdMetaTrailer(markdown) {
+    let markerAt = -1;
+    let lineStart = 0;
+    while (lineStart <= markdown.length) {
+        const newlineAt = markdown.indexOf('\n', lineStart);
+        const lineEnd = newlineAt < 0 ? markdown.length : newlineAt;
+        const line = markdown.slice(lineStart, lineEnd).replace(/\r$/, '');
+        if (line === KTD_META_MARKER) {
+            markerAt = lineStart;
         }
+        if (newlineAt < 0)
+            break;
+        lineStart = newlineAt + 1;
     }
-    // Single element: return just the text (most common case — root element doc)
-    if (elements.length === 1) {
-        return elements[0].text;
+    if (markerAt < 0)
+        return markdown;
+    const trailer = markdown.slice(markerAt + KTD_META_MARKER.length);
+    const strayHeading = trailer.match(KTD_HEADING_LINE);
+    if (strayHeading) {
+        throw new Error(`KTD documentation update has a "## ${strayHeading[1].trim()}" section below the read-only SAPRead ` +
+            `marker "${KTD_META_MARKER}". Move the section above that line, or remove the marker and its context.`);
     }
-    // Multiple elements: format as structured Markdown with element headings
-    return elements.map((e) => `## ${e.id}\n\n${e.text}`).join('\n\n');
+    return markdown.slice(0, markerAt).trimEnd();
 }
 /**
- * Replace the <sktd:text> body of a <sktd:docu> envelope with base64(markdown),
- * preserving all other attributes and elements (responsible, packageRef, refObject, etc.).
+ * Replace the per-node <sktd:text> bodies of a <sktd:docu> envelope with
+ * base64(markdown), preserving all other attributes and elements (responsible,
+ * packageRef, refObject, and every node the body does not address).
+ *
+ * ADDRESSING: a KTD holds one <sktd:element> per documented node — the object
+ * root plus one per documentable element (BDEF actions, savers, entities, …).
+ * `decodeKtdText` renders those as `## <node id>` sections, and this function
+ * consumes that exact-id section format to write each section back to its node.
+ * A body that addresses no node used to be written into whichever element came
+ * first, which silently overwrote the root and dropped every other node's edit.
  *
  * The returned XML is suitable for a PUT to the KTD object URL with
  * content-type `application/vnd.sap.adt.sktdv2+xml`.
  */
-export function rewriteKtdText(envelopeXml, markdown) {
-    const base64 = Buffer.from(markdown, 'utf-8').toString('base64');
-    const textPattern = /(<sktd:text[^>]*>)([\s\S]*?)(<\/sktd:text>)/;
-    if (textPattern.test(envelopeXml)) {
-        return envelopeXml.replace(textPattern, `$1${base64}$3`);
+export function rewriteKtdText(envelopeXml, markdown, report) {
+    const hasReadOnlyContext = markdown.split(/\r?\n/).includes(KTD_META_MARKER);
+    markdown = stripKtdMetaTrailer(markdown);
+    if (!markdown.trim()) {
+        throw new Error('KTD documentation update has an empty body. ARC-1 will not erase documentation from a bodyless ' +
+            'update; to clear one node, address it with "## <node id>" followed by an empty section.');
     }
-    // Self-closing form: <sktd:text ... /> (rare but possible on an empty KTD)
-    const selfClosing = /<sktd:text([^>]*)\/>/;
-    if (selfClosing.test(envelopeXml)) {
-        return envelopeXml.replace(selfClosing, `<sktd:text$1>${base64}</sktd:text>`);
+    const elements = findKtdElements(envelopeXml);
+    const routes = ktdRoutes(envelopeXml, elements);
+    assertWritableKtdRoutes(routes);
+    const documented = elements.filter((element) => elementBase64(element.xml));
+    const root = rootKtdElement(envelopeXml, elements);
+    const unaddressedTarget = documented.length <= 1 ? (documented[0] ?? root) : undefined;
+    // A route-safe SAPRead prefixes one backslash to body H2s that would otherwise
+    // be parsed as node boundaries. Its presence makes a lone root route unambiguous,
+    // even when that read had no metadata context to append. Compute the inverse once
+    // as well so the unaddressed/recovery path cannot persist the transport escape.
+    const routeUnescapedMarkdown = unescapeKtdBodyRouteHeadings(markdown, routes);
+    const hasBodyRouteEscape = routeUnescapedMarkdown !== markdown;
+    const unescapedMarkdown = unescapeKtdBodyMetaMarkers(routeUnescapedMarkdown);
+    const perElement = splitKtdMarkdownByElementId(markdown, routes, report);
+    if (perElement) {
+        // The root id is a bare ABAP object name, so a lone `## ZI_FOO` is also a very
+        // natural document title. When the unaddressed fallback already resolves to that
+        // root, consuming the line as routing syntax would silently delete the title.
+        // A complete SAPRead result is unambiguous because it carries the metadata marker;
+        // several addressed nodes are likewise unambiguous. Refuse the remaining collision.
+        if (!hasReadOnlyContext &&
+            !hasBodyRouteEscape &&
+            root &&
+            root.id.toUpperCase() === envelopeKtdName(envelopeXml).toUpperCase() &&
+            unaddressedTarget === root &&
+            perElement.size === 1 &&
+            perElement.has(root.id)) {
+            throw new Error(`KTD heading "## ${root.id}" is ambiguous: it can be the root-node route or a visible Markdown title. ` +
+                `ARC-1 will not silently remove it. Omit that heading to update the sole root body, use "# ${root.id}" ` +
+                'for a visible title, or start a multi-node edit from the complete SAPRead result.');
+        }
+        return rewriteKtdElementTexts(envelopeXml, elements, perElement);
     }
+    // An unaddressed body still has one unambiguous destination whenever at most one
+    // node currently holds text — that is exactly what `decodeKtdText` rendered, and
+    // it is the shape a freshly created KTD comes back in. More than one documented
+    // node, though, and the body would overwrite one and silently drop the others.
+    if (documented.length > 1) {
+        const addressable = documented.map((element) => element.id).filter(Boolean);
+        throw new Error(`KTD documentation update addresses no node. "${envelopeKtdName(envelopeXml)}" documents ` +
+            `${documented.length} nodes, so the body must address them with "## <node id>" headings. ` +
+            `Documented node ids in the version this write would modify:\n${addressable.map((id) => `  ${id}`).join('\n')}`);
+    }
+    const target = unaddressedTarget;
+    if (target) {
+        return (envelopeXml.slice(0, target.start) + setKtdElementText(target, unescapedMarkdown) + envelopeXml.slice(target.end));
+    }
+    // No <sktd:element> at all — rewrite the lone <sktd:text> wherever it sits.
+    const spliced = spliceKtdTextBody(envelopeXml, unescapedMarkdown);
+    if (spliced !== undefined)
+        return spliced;
     throw new Error('KTD envelope missing <sktd:text> element — cannot update documentation body.');
 }
+/** Eclipse ADT applies this limit to its KTD short-text input widget. */
+export const KTD_SHORT_TEXT_MAX_LENGTH = 60;
+/**
+ * Apply optional Markdown bodies and optional short texts to one server-provided envelope.
+ * All mutations stay local until validation succeeds and the caller performs the PUT.
+ */
+export function rewriteKtdDocument(envelopeXml, markdown, shortTexts, report) {
+    const assignments = shortTexts ?? [];
+    if (markdown === undefined && assignments.length === 0) {
+        throw new Error('KTD documentation update has nothing to write: pass "source" (node bodies), "shortTexts", or both.');
+    }
+    const withBodies = markdown === undefined ? envelopeXml : rewriteKtdText(envelopeXml, markdown, report);
+    return assignments.length === 0 ? withBodies : rewriteKtdShortTexts(withBodies, assignments);
+}
+/** Base64 payload currently held by an element, '' when it is empty or absent. */
+function elementBase64(elementXml) {
+    return elementXml.match(/<sktd:text[^>]*>([\s\S]*?)<\/sktd:text>/)?.[1]?.trim() ?? '';
+}
+/** Mirror Eclipse KtdElementUtil.canHaveLongText while retaining old envelopes with no flags. */
+function canWriteKtdLongText(elementXml) {
+    const obligation = elementXml.match(/\bsktd:longTextObligation="([^"]*)"/)?.[1]?.toLowerCase();
+    if (obligation)
+        return obligation === 'mandatory' || obligation === 'optional';
+    const canHaveDocumentation = elementXml.match(/\bsktd:canHaveDocumentation="([^"]*)"/)?.[1]?.toLowerCase();
+    if (canHaveDocumentation)
+        return canHaveDocumentation === 'true';
+    // Older/simplified envelopes do not always carry either optional attribute. The
+    // server-provided text slot remains the strongest backwards-compatible evidence.
+    return /<sktd:text(?:\s|\/|>)/.test(elementXml);
+}
+const KTD_SHORT_TEXT_TAG = /<sktd:shortText\b[^>]*\/?>/;
+const KTD_SHORT_TEXT_VALUE = /\bsktd:text="([^"]*)"/;
+const KTD_SHORT_TEXT_OBLIGATION = /\bsktd:obligation="([^"]*)"/;
+/** Existing short texts, each labelled with a reference that resolves back to its node. */
+export function formatKtdShortTexts(envelopeXml) {
+    const elements = findKtdElements(envelopeXml);
+    const routes = ktdRoutes(envelopeXml, elements);
+    const lines = elements
+        .map((element) => {
+        const tag = element.xml.match(KTD_SHORT_TEXT_TAG)?.[0];
+        const encoded = tag?.match(KTD_SHORT_TEXT_VALUE)?.[1] ?? '';
+        if (!element.id || !encoded)
+            return undefined;
+        const text = Buffer.from(encoded, 'base64').toString('utf-8').replace(/\s+/g, ' ').trim();
+        if (!text)
+            return undefined;
+        const obligation = tag?.match(KTD_SHORT_TEXT_OBLIGATION)?.[1] || 'unspecified';
+        return `  ${addressableKtdRoute(routes, element)} [${obligation}]: ${text}`;
+    })
+        .filter((line) => Boolean(line));
+    return lines.length === 0
+        ? ''
+        : [
+            routes.duplicateIds.size > 0
+                ? 'Short texts (read-only; duplicate node IDs prevent updates):'
+                : 'Short texts (read-only; update with SAPWrite shortTexts=[{node,text}] using the name shown):',
+            ...lines,
+        ].join('\n');
+}
+/** Validate all assignments, then splice only their existing short-text value attributes. */
+function rewriteKtdShortTexts(envelopeXml, assignments) {
+    const elements = findKtdElements(envelopeXml);
+    // The same resolver the "## " section headings use, so one spelling addresses a node
+    // everywhere: exact id, case variant, or the node name the SAPRead index prints.
+    const routes = ktdRoutes(envelopeXml, elements);
+    assertWritableKtdRoutes(routes);
+    const resolved = new Map();
+    for (const assignment of assignments) {
+        const requestedId = assignment.node.trim();
+        const element = resolveKtdRoute(routes, requestedId);
+        if (!element)
+            throw unknownKtdNodeError([requestedId], routes);
+        const key = element.id;
+        if (resolved.has(key)) {
+            throw new Error(`KTD node "${element.id}" appears twice in shortTexts — keep one entry per node.`);
+        }
+        const text = assignment.text.replace(/\s+/g, ' ').trim();
+        if (text.length > KTD_SHORT_TEXT_MAX_LENGTH) {
+            throw new Error(`Short text for KTD node "${element.id}" is ${text.length} characters; Eclipse ADT allows ` +
+                `${KTD_SHORT_TEXT_MAX_LENGTH}.`);
+        }
+        const tag = element.xml.match(KTD_SHORT_TEXT_TAG)?.[0];
+        if (!tag || !KTD_SHORT_TEXT_VALUE.test(tag)) {
+            throw new Error(`KTD node "${element.id}" has no writable <sktd:shortText sktd:text="…"> value; ARC-1 will not synthesize one.`);
+        }
+        const obligation = tag.match(KTD_SHORT_TEXT_OBLIGATION)?.[1]?.toLowerCase();
+        if (obligation !== 'mandatory' && obligation !== 'optional') {
+            throw new Error(`KTD node "${element.id}" does not take a writable short text ` +
+                `(sktd:obligation="${obligation ?? 'missing'}"; expected "mandatory" or "optional").`);
+        }
+        resolved.set(key, { element, text });
+    }
+    let rewritten = envelopeXml;
+    for (const { element, text } of [...resolved.values()].sort((left, right) => right.element.start - left.element.start)) {
+        const encoded = text ? Buffer.from(text, 'utf-8').toString('base64') : '';
+        const replacement = element.xml.replace(KTD_SHORT_TEXT_TAG, (tag) => tag.replace(KTD_SHORT_TEXT_VALUE, `sktd:text="${encoded}"`));
+        rewritten = rewritten.slice(0, element.start) + replacement + rewritten.slice(element.end);
+    }
+    return rewritten;
+}
+/**
+ * The element documenting the object itself, for an envelope where nothing is
+ * documented yet. Live reads show the root node's `<sktd:id>` repeating the
+ * object name from `<sktd:docu adtcore:name>`; when nothing matches, fall back to
+ * document order, which is where an unaddressed body has always gone.
+ */
+function rootKtdElement(envelopeXml, elements) {
+    const name = envelopeKtdName(envelopeXml);
+    return (elements.find((element) => element.id === name) ??
+        elements.find((element) => element.id.toUpperCase() === name.toUpperCase()) ??
+        elements[0]);
+}
+/** `<sktd:element>` blocks, paired or self-closing, in document order. */
+function findKtdElements(envelopeXml) {
+    const pattern = /<sktd:element\b(?:[^>]*\/>|[\s\S]*?<\/sktd:element>)/g;
+    const elements = [];
+    let match;
+    while ((match = pattern.exec(envelopeXml)) !== null) {
+        const xml = match[0];
+        elements.push({
+            id: xml.match(/<sktd:id>([\s\S]*?)<\/sktd:id>/)?.[1]?.trim() ?? '',
+            start: match.index,
+            end: match.index + xml.length,
+            xml,
+        });
+    }
+    return elements;
+}
+function envelopeKtdName(envelopeXml) {
+    return envelopeXml.match(/<sktd:docu\b[^>]*\badtcore:name="([^"]*)"/)?.[1] ?? 'this KTD';
+}
+/**
+ * Every spelling a node name is seen in: percent-decoded (`%_OWN`, what the index prints) and raw
+ * as SAP encodes it on the wire (`%25_OWN`, what every `## <full id>` heading carries). One entry
+ * when they coincide. Both must be routes, or the spelling a caller copies from one surface is
+ * prose on the other.
+ * SAP's optional displayName is a presentation label, not an address; never route by it.
+ */
+function ktdNodeNameSpellings(id) {
+    const at = id.indexOf(';name=');
+    const raw = at < 0 ? id : id.slice(at + ';name='.length);
+    try {
+        return [...new Set([decodeURIComponent(raw), raw])];
+    }
+    catch {
+        return [raw];
+    }
+}
+function ktdRoutes(envelopeXml, elements) {
+    const byId = new Map();
+    const duplicateIds = new Set();
+    const byFoldedId = new Map();
+    const byName = new Map();
+    const qualifiers = new Set();
+    const register = (map, key, element) => {
+        const candidates = map.get(key) ?? [];
+        if (!candidates.includes(element))
+            candidates.push(element);
+        map.set(key, candidates);
+    };
+    for (const element of elements) {
+        if (!element.id)
+            continue;
+        if (byId.has(element.id))
+            duplicateIds.add(element.id);
+        else
+            byId.set(element.id, element);
+        register(byFoldedId, element.id.toUpperCase(), element);
+        for (const spelling of ktdNodeNameSpellings(element.id)) {
+            const nameKey = spelling.toUpperCase();
+            register(byName, nameKey, element);
+            const dot = spelling.lastIndexOf('.');
+            if (dot > 0)
+                qualifiers.add(spelling.slice(0, dot).toUpperCase());
+        }
+    }
+    const objectName = envelopeKtdName(envelopeXml);
+    return {
+        objectName,
+        byId,
+        duplicateIds,
+        byFoldedId,
+        byName,
+        qualifiers,
+        namespace: objectName.match(/^\/[^/]+\//)?.[0].toUpperCase() ?? '',
+    };
+}
+/** Ambiguous envelopes remain inspectable; only mutation requires unique exact IDs. */
+function assertWritableKtdRoutes(routes) {
+    if (routes.duplicateIds.size > 0) {
+        throw new Error(`KTD envelope contains duplicate node ids (${[...routes.duplicateIds].join(', ')}); ARC-1 cannot address these elements separately.`);
+    }
+}
+/**
+ * Shared lookup precedence: exact ID, then case-insensitive ID, then indexed node name.
+ * Keep ambiguous candidates so writers can refuse them and readers can choose a full-ID label.
+ */
+function ktdRouteCandidates(routes, heading) {
+    const exact = routes.duplicateIds.has(heading) ? undefined : routes.byId.get(heading);
+    if (exact)
+        return [exact];
+    const key = heading.toUpperCase();
+    return routes.byFoldedId.get(key) ?? routes.byName.get(key) ?? [];
+}
+/** Writes require one target; display labels can fall back to the full ID without throwing. */
+function resolveKtdRoute(routes, heading) {
+    const candidates = ktdRouteCandidates(routes, heading);
+    if (candidates.length > 1) {
+        throw new Error(`KTD node "${heading}" is ambiguous in "${routes.objectName}" — ${candidates.length} nodes carry ` +
+            `that reference. Address one by its exact full id:\n${candidates.map((element) => `  ${element.id}`).join('\n')}`);
+    }
+    return candidates[0];
+}
+/**
+ * Whether an unresolved heading is unmistakably meant as a node reference — an ADT URI, a `#type=`
+ * fragment, a name qualified by an entity this document knows, a name in the documented object's
+ * own namespace, or an index label copied with its "(empty)" marker. Such a heading is a typo or
+ * a node that does not exist, and folding it into the previous node's text is exactly the silent
+ * corruption this guard exists to prevent. Ordinary prose headings ("## Shape", "## Where the data
+ * comes from") match none of these; a prose heading that does can be kept as prose with a leading
+ * backslash (`\## …`), the same escape the route-safe read uses.
+ */
+function looksLikeKtdRoute(routes, heading) {
+    const key = heading.toUpperCase();
+    if (key.startsWith('/SAP/BC/ADT/') || key.includes('#TYPE=') || /\(empty\)$/i.test(heading))
+        return true;
+    if (routes.namespace && key.startsWith(routes.namespace))
+        return true;
+    return [...routes.qualifiers].some((qualifier) => key.startsWith(`${qualifier}.`));
+}
+/**
+ * Refusal for a node reference that matches nothing. Lists the known nodes by the spelling the
+ * SAPRead index prints (a name, or the full id where only that resolves), so a typo can be matched
+ * against the list by eye instead of against ~140-character URIs.
+ */
+function unknownKtdNodeError(refs, routes) {
+    const subject = refs.length === 1
+        ? `KTD node "${refs[0]}" does not`
+        : `KTD nodes ${refs.map((ref) => `"${ref}"`).join(', ')} do not`;
+    const known = [...routes.byId.values()].map((element) => `  ${addressableKtdRoute(routes, element)}`);
+    return new Error(`${subject} exist in this document. SAP creates one <sktd:element> per documentable element of ` +
+        'the referenced object; ARC-1 will not invent one. A heading meant as prose can be kept as prose with a ' +
+        'leading backslash ("\\## …"). Known node ids (any spelling below is accepted):\n' +
+        known.join('\n'));
+}
+/**
+ * Split a Markdown body in the section format emitted by `decodeKtdText`.
+ *
+ * A line is a node boundary when it is `## ` followed by something `resolveKtdRoute` maps to an
+ * element of this envelope: its exact id, a case variant, or the node NAME SAPRead's index prints.
+ * Names resolve against EVERY node, documented or not — resolving them against the pending ones
+ * only made a second write to the same node silently fold its section into the previous node's
+ * body. A heading that is unmistakably a node reference but matches nothing aborts the write.
+ * Ordinary Markdown headings inside a node's documentation survive the round-trip untouched.
+ *
+ * Returns undefined when the body addresses no node (single-node KTD, or a freshly
+ * created one); the caller then treats the whole body as that one node's text.
+ */
+function splitKtdMarkdownByElementId(markdown, routes, report) {
+    const lines = markdown.split(/\r?\n/);
+    const headings = [];
+    const unknown = [];
+    lines.forEach((line, index) => {
+        const id = line.match(KTD_HEADING_LINE)?.[1].trim();
+        if (!id)
+            return;
+        const resolved = resolveKtdRoute(routes, id);
+        if (resolved)
+            headings.push({ line: index, id: resolved.id });
+        else if (routes.byId.size > 0 && looksLikeKtdRoute(routes, id))
+            unknown.push(id);
+        // Nothing distinguishes a typo in a bare node name from a prose heading when the document's
+        // names carry no qualifier (DDLS fields, for instance) — so the caller is told what stayed prose.
+        else if (routes.byId.size > 0)
+            report?.proseHeadings.push(id);
+    });
+    if (unknown.length > 0)
+        throw unknownKtdNodeError(unknown, routes);
+    if (headings.length === 0)
+        return undefined;
+    const preamble = lines.slice(0, headings[0].line).join('\n').trim();
+    if (preamble) {
+        throw new Error(`KTD documentation update has text before its first "## <node id>" heading (the one for ` +
+            `"${headings[0].id}"). Every line must belong to a node, so move that text under a heading. ` +
+            `Stray text starts: "${preamble.slice(0, 80)}"`);
+    }
+    const bodies = new Map();
+    headings.forEach((heading, index) => {
+        const until = index + 1 < headings.length ? headings[index + 1].line : lines.length;
+        if (bodies.has(heading.id)) {
+            throw new Error(`KTD node "${heading.id}" appears twice in the update body — keep one section per node.`);
+        }
+        const body = lines
+            .slice(heading.line + 1, until)
+            .join('\n')
+            .trim();
+        bodies.set(heading.id, unescapeKtdBodyMetaMarkers(unescapeKtdBodyRouteHeadings(body, routes)));
+    });
+    return bodies;
+}
+/**
+ * A heading shape reserved by the section parser, whether it resolves or aborts the write.
+ * Node NAMES are reserved too, so a prose heading that happens to equal one is escaped on read
+ * and restored on write instead of being consumed as a route.
+ */
+function isKtdRouteHeadingId(id, routes) {
+    const key = id.toUpperCase();
+    return routes.byFoldedId.has(key) || routes.byName.has(key) || looksLikeKtdRoute(routes, id);
+}
+/**
+ * Protect a stored body line that is indistinguishable from KTD section routing.
+ *
+ * One leading backslash is added to every run of zero or more existing backslashes,
+ * so the inverse can remove exactly the transport escape and preserve the stored text.
+ */
+function escapeKtdBodyRouteHeadings(markdown, routes) {
+    return markdown.replace(/^(\\*)(##[ \t]+.*)$/gm, (line, _slashes, heading) => {
+        const id = heading.match(KTD_HEADING_LINE)?.[1].trim();
+        return id && isKtdRouteHeadingId(id, routes) ? `\\${line}` : line;
+    });
+}
+/** Remove the one transport escape added by `escapeKtdBodyRouteHeadings`. */
+function unescapeKtdBodyRouteHeadings(markdown, routes) {
+    return markdown.replace(/^\\(\\*##[ \t]+.*)$/gm, (line, escapedHeading) => {
+        const heading = escapedHeading.replace(/^\\*/, '');
+        const id = heading.match(KTD_HEADING_LINE)?.[1].trim();
+        return id && isKtdRouteHeadingId(id, routes) ? escapedHeading : line;
+    });
+}
+/** Escape an exact metadata-marker body line without losing existing leading backslashes. */
+function escapeKtdBodyMetaMarkers(markdown) {
+    const marker = escapeRegExp(KTD_META_MARKER);
+    return markdown.replace(new RegExp(`^(\\\\*)${marker}(\\r?)$`, 'gm'), (line) => `\\${line}`);
+}
+/** Remove the one transport escape added by `escapeKtdBodyMetaMarkers`. */
+function unescapeKtdBodyMetaMarkers(markdown) {
+    const marker = escapeRegExp(KTD_META_MARKER);
+    return markdown.replace(new RegExp(`^\\\\(\\\\*${marker})(\\r?)$`, 'gm'), (_line, escapedMarker, carriageReturn) => `${escapedMarker}${carriageReturn}`);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Splice new base64 bodies into the addressed elements, leaving every other byte alone. */
+function rewriteKtdElementTexts(envelopeXml, elements, bodies) {
+    let rewritten = envelopeXml;
+    // Back to front, so the elements still ahead keep their offsets.
+    for (const element of [...elements].reverse()) {
+        const body = bodies.get(element.id);
+        if (body === undefined)
+            continue;
+        rewritten = rewritten.slice(0, element.start) + setKtdElementText(element, body) + rewritten.slice(element.end);
+    }
+    return rewritten;
+}
+function setKtdElementText(element, markdown) {
+    const current = decodeKtdElementText(element.xml);
+    // A complete SAPRead result includes documented nodes even when SAP marks one of
+    // them non-writable. Preserve an unchanged section byte-for-byte; only an attempted
+    // mutation needs the writability gate below.
+    if (current !== undefined && normalizeKtdBodyForComparison(current) === normalizeKtdBodyForComparison(markdown)) {
+        return element.xml;
+    }
+    const spliced = spliceKtdTextBody(element.xml, markdown);
+    if (spliced === undefined) {
+        throw new Error(`KTD node "${element.id}" has no <sktd:text> element to write into. SAP gives every documentable ` +
+            `node an (initially empty) <sktd:text/>, so an element without one is not a documentation target; ` +
+            `ARC-1 does not synthesize one.`);
+    }
+    if (!canWriteKtdLongText(element.xml)) {
+        throw new Error(`KTD node "${element.id}" does not accept long-text documentation according to SAP's ` +
+            'canHaveDocumentation/longTextObligation contract.');
+    }
+    return spliced;
+}
+/** Decode one existing text slot; undefined means the element has no slot at all. */
+function decodeKtdElementText(elementXml) {
+    const paired = elementXml.match(/<sktd:text[^>]*>([\s\S]*?)<\/sktd:text>/);
+    if (paired) {
+        const base64 = paired[1].trim();
+        return base64 ? Buffer.from(base64, 'base64').toString('utf-8') : '';
+    }
+    return /<sktd:text(?:\s[^>]*)?\/>/.test(elementXml) ? '' : undefined;
+}
+/** Section separators normalize outer whitespace and CRLF; compare the semantic body. */
+function normalizeKtdBodyForComparison(markdown) {
+    return markdown.replace(/\r\n/g, '\n').trim();
+}
+/**
+ * Swap the payload of the first <sktd:text> in `xml` — paired or self-closing — for
+ * base64(markdown). Returns undefined when `xml` holds no <sktd:text> at all, so each
+ * caller raises the error that fits its own context. `<sktd:shortText sktd:text="…"/>`
+ * never matches: the literal `<sktd:text` requires the element name, not the attribute.
+ */
+function spliceKtdTextBody(xml, markdown) {
+    const base64 = Buffer.from(markdown, 'utf-8').toString('base64');
+    const paired = /(<sktd:text[^>]*>)([\s\S]*?)(<\/sktd:text>)/;
+    if (paired.test(xml))
+        return xml.replace(paired, `$1${base64}$3`);
+    const selfClosing = /<sktd:text([^>]*)\/>/;
+    if (selfClosing.test(xml))
+        return xml.replace(selfClosing, `<sktd:text$1>${base64}</sktd:text>`);
+    return undefined;
+}
 //# sourceMappingURL=ddic-xml.js.map