@cspeach/cli 0.9.0 → 1.1.0

package/dist/tools/extend-model/anchored-insert.js

@@ -0,0 +1,1414 @@
+/**
+ * Anchored insertion for ABAP CDS / DDLX source (B1 of the revision-aware
+ * design). We deliberately do NOT parse the DSL into a model and re-serialize
+ * — a lossless CDS/BDEF round-trip is a weeks-long sub-project and a half-built
+ * serializer corrupts more than it protects. Instead we locate a stable
+ * textual anchor and insert the new element there, leaving every other byte
+ * untouched. The corruption surface is the inserted span only; the real safety
+ * net is the skill's snapshot → preview-diff → syntax-check → activate-verify →
+ * rollback chain around this pure function.
+ *
+ * See docs/superpowers/specs/2026-06-24-revision-aware-cspeach-design.md §5.2.
+ */
+/**
+ * Base indentation of the element whose final line is `lastIdx`: the
+ * shallowest indentation among the contiguous run of non-empty lines ending
+ * at `lastIdx`, scanning upward and stopping at the first blank line (the
+ * element separator) or the first line that leaves the view/annotate body
+ * (a zero-indent line such as the opening `{`).
+ *
+ * Annotation lines and the element's first line sit at this base indent;
+ * continuation lines of a multi-line expression are deeper, so the minimum
+ * yields the element's own indentation rather than a deep continuation line.
+ * Returns '' if no indented line is found (caller may apply a default).
+ */
+function baseIndentOfLastElement(lines, lastIdx) {
+    let minIndent = '';
+    let minLen = Infinity;
+    for (let i = lastIdx; i >= 0; i--) {
+        const trimmed = lines[i].trim();
+        if (trimmed === '')
+            break; // element separator
+        const indent = (lines[i].match(/^\s*/) ?? [''])[0];
+        if (indent.length === 0)
+            break; // left the body (e.g. the opening brace)
+        if (indent.length < minLen) {
+            minLen = indent.length;
+            minIndent = indent;
+        }
+    }
+    return minIndent;
+}
+/**
+ * Insert a new field into a CDS `define view [entity] … { … }` element list.
+ *
+ * The new field is appended as the last element before the body's closing
+ * brace, matching the indentation of the existing last element. CDS element
+ * lists separate elements with commas and the last element carries no trailing
+ * comma, so the previously-last element gains a comma.
+ *
+ * @param source   full CDS view source
+ * @param fieldDef the element to add, e.g. `Priority` or `priority as Priority`
+ *                 (no leading indentation, no trailing comma — both are applied)
+ * @returns the modified source
+ */
+export function insertCdsField(source, fieldDef) {
+    const lines = source.split('\n');
+    // Anchor: the view body's closing brace — the last line that is just '}'.
+    let braceIdx = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (lines[i].trim() === '}') {
+            braceIdx = i;
+            break;
+        }
+    }
+    if (braceIdx === -1) {
+        throw new Error('insertCdsField: no closing brace found for the view body');
+    }
+    // The last existing element: the last non-empty line before the brace.
+    let lastIdx = -1;
+    for (let i = braceIdx - 1; i >= 0; i--) {
+        if (lines[i].trim() !== '') {
+            lastIdx = i;
+            break;
+        }
+    }
+    if (lastIdx === -1) {
+        throw new Error('insertCdsField: no element found in the view body');
+    }
+    // Reuse the last element's *base* indentation for the new one. The last
+    // element may span multiple lines (e.g. a multi-line CASE/CAST expression)
+    // whose final line is indented far deeper than the element's own start.
+    // Reusing that final line's indent would mis-indent the new element, so
+    // derive the base indent from the shallowest line of the element's block.
+    const indent = baseIndentOfLastElement(lines, lastIdx);
+    // Ensure the prior last element ends with a comma.
+    if (!lines[lastIdx].trimEnd().endsWith(',')) {
+        lines[lastIdx] = `${lines[lastIdx].trimEnd()},`;
+    }
+    // Insert the new field immediately before the closing brace.
+    lines.splice(braceIdx, 0, `${indent}${fieldDef}`);
+    return lines.join('\n');
+}
+/**
+ * Insert an `@UI.lineItem`-annotated field into a DDLX metadata extension
+ * (`annotate view … with { … }`) so the field appears as a column in a Fiori
+ * Elements List Report. The annotated field block is appended before the
+ * body's closing brace, matching the indentation of the existing entries.
+ *
+ * DDLX entries are `;`-terminated independently, so — unlike a CDS element
+ * list — no prior entry needs editing.
+ *
+ * @param source   full DDLX metadata-extension source
+ * @param field    the field name to expose as a column, e.g. `Priority`
+ * @param position the `@UI.lineItem` position (column order)
+ * @returns the modified source
+ */
+export function insertDdlxLineItem(source, field, position) {
+    const lines = source.split('\n');
+    // Anchor: the body's closing brace — the last line that is just '}'.
+    let braceIdx = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (lines[i].trim() === '}') {
+            braceIdx = i;
+            break;
+        }
+    }
+    if (braceIdx === -1) {
+        throw new Error('insertDdlxLineItem: no closing brace found for the annotate body');
+    }
+    // Reuse the base indentation of the last entry (default 2 spaces). Using
+    // the element's shallowest line keeps the new entry aligned even when the
+    // last entry spans multiple lines.
+    let lastIdx = -1;
+    for (let i = braceIdx - 1; i >= 0; i--) {
+        const trimmed = lines[i].trim();
+        if (trimmed !== '' && trimmed !== '{') {
+            lastIdx = i;
+            break;
+        }
+    }
+    const indent = lastIdx === -1 ? '  ' : baseIndentOfLastElement(lines, lastIdx) || '  ';
+    // Insert the annotation line followed by the field line.
+    lines.splice(braceIdx, 0, `${indent}@UI.lineItem: [{ position: ${position} }]`, `${indent}${field};`);
+    return lines.join('\n');
+}
+/**
+ * Promote an element that is ALREADY exposed in a CDS `define view [entity]`
+ * projection to a Fiori Elements list column, by inserting an
+ * `@UI.lineItem` annotation directly above the element's declaration line.
+ *
+ * Unlike {@link insertCdsField} (which APPENDS a new element to the body) this
+ * function annotates a field that is already in the element list — closing the
+ * gap where the model only knew how to add fields, not surface existing ones.
+ *
+ * The anchor is the element's own declaration line, located by matching the
+ * declared element name (the alias after `as`, or the bare/`key`-prefixed
+ * name). The new annotation is inserted immediately above that line at the
+ * same indentation, so it joins any existing contiguous annotation block.
+ *
+ * Fail-safe by design:
+ *  - Refuses (throws) when the field cannot be uniquely identified (not found,
+ *    or ambiguous across multiple declarations).
+ *  - Refuses multi-line / computed elements (e.g. a `case … end as Name`): the
+ *    declaration line is a continuation of a larger expression, and inserting
+ *    above it would split that expression. Such elements must be promoted
+ *    manually or via /abap-refactor.
+ *  - Idempotent: refuses when the field already carries an `@UI.lineItem` in the
+ *    contiguous annotation block directly above it, so re-running is a no-op
+ *    error rather than a duplicate column.
+ *
+ * @param source   full CDS view source
+ * @param field    the EXISTING exposed element name to promote, e.g. `CreatedBy`
+ * @param position the `@UI.lineItem` position (column order)
+ * @returns the modified source
+ */
+export function promoteCdsFieldToLineItem(source, field, position) {
+    const lines = source.split('\n');
+    // The element name a line declares, or null. Strip trailing whitespace, then
+    // a single optional trailing comma, then trailing whitespace again:
+    //   `expr as Name`  -> Name   (aliased element)
+    //   `key Name` / `Name` (bare) -> Name
+    //   anything else (continuation, brace, annotation, expression) -> null
+    const declaredName = (line) => {
+        const s = line.replace(/\s+$/, '').replace(/,$/, '').replace(/\s+$/, '');
+        const aliased = s.match(/\bas\s+(\w+)$/);
+        if (aliased)
+            return aliased[1];
+        const bare = s.trim().match(/^(?:key\s+)?(\w+)$/);
+        if (bare)
+            return bare[1];
+        return null;
+    };
+    // 1. Locate the unique element declaring `field`.
+    const defIdxs = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (declaredName(lines[i]) === field)
+            defIdxs.push(i);
+    }
+    if (defIdxs.length === 0) {
+        throw new Error(`promoteCdsFieldToLineItem: field '${field}' not found in the view element list`);
+    }
+    if (defIdxs.length > 1) {
+        throw new Error(`promoteCdsFieldToLineItem: field '${field}' is ambiguous (${defIdxs.length} matches)`);
+    }
+    const defIdx = defIdxs[0];
+    // 2. Refuse if defIdx is a continuation line of a multi-line element —
+    //    inserting above it would split the expression. A "fresh start" (safe)
+    //    is only when the line above is blank, the opening brace, an annotation,
+    //    or the previous element's terminator (ends with a comma).
+    const prev = defIdx > 0 ? lines[defIdx - 1].trim() : '';
+    const isFreshStart = prev === '' || prev === '{' || prev.startsWith('@') || prev.endsWith(',');
+    if (!isFreshStart) {
+        throw new Error(`promoteCdsFieldToLineItem: '${field}' resolves to a multi-line/computed element; promote it manually or via /abap-refactor`);
+    }
+    // 3. Idempotency: refuse if `field` already has an @UI.lineItem in the
+    //    contiguous single-line annotation block directly above defIdx.
+    for (let i = defIdx - 1; i >= 0 && lines[i].trim().startsWith('@'); i--) {
+        if (/@UI\.lineItem\b/.test(lines[i])) {
+            throw new Error(`promoteCdsFieldToLineItem: '${field}' is already exposed as a column (@UI.lineItem present)`);
+        }
+    }
+    // 4. Insert the annotation immediately above defIdx, matching defIdx's indent.
+    const indent = (lines[defIdx].match(/^\s*/) ?? [''])[0];
+    lines.splice(defIdx, 0, `${indent}@UI.lineItem: [{ position: ${position} }]`);
+    return lines.join('\n');
+}
+/**
+ * Add a NON-KEY field to a CDS `define table NAME { … }` body (B2a — the first
+ * leg of the table→CDS→BDEF single-field chain).
+ *
+ * Like {@link insertDdlxLineItem}, table fields are `;`-terminated independently
+ * — there is no comma-separated element list — so NO prior line is edited; only
+ * the new line is inserted. The new field is appended as the last entry before
+ * the body's closing brace, at the indentation of the existing last entry.
+ *
+ * No DSL parser is used: the anchor is the textual closing brace (the last line
+ * whose trim() === '}'), exactly as the CDS/DDLX helpers do.
+ *
+ * Fail-safe by design:
+ *  - Refuses (throws) a `key …` clause: adding/removing a key is a destructive
+ *    DDIC table-conversion, never a safe append. Only non-key fields at the end
+ *    are supported.
+ *  - Throws when no closing brace can be found for the table body.
+ *
+ * @param source      full CDS `define table` source
+ * @param fieldClause the field definition WITHOUT a trailing `;`, e.g.
+ *                    `reference : zde_reference` or `reference : abap.char(16)`.
+ *                    Any trailing `;`/whitespace is stripped and exactly one
+ *                    `;` is re-applied.
+ * @returns the modified source
+ */
+export function addTableField(source, fieldClause) {
+    // Fail-safe: never touch keys.
+    if (/^\s*key\s/i.test(fieldClause)) {
+        throw new Error('addTableField: refusing to add a key field (key changes are destructive); only non-key fields at the end are supported');
+    }
+    // Normalize: strip trailing whitespace, then any trailing ';', then
+    // whitespace again — the function re-adds exactly one ';'.
+    const normalizedClause = fieldClause.replace(/\s+$/, '').replace(/;$/, '').replace(/\s+$/, '');
+    const lines = source.split('\n');
+    // Anchor: the body's closing brace — the last line that is just '}'.
+    let braceIdx = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (lines[i].trim() === '}') {
+            braceIdx = i;
+            break;
+        }
+    }
+    if (braceIdx === -1) {
+        throw new Error('addTableField: no closing brace found for the table body');
+    }
+    // Reuse the base indent of the last entry (default 2 spaces).
+    let lastIdx = -1;
+    for (let i = braceIdx - 1; i >= 0; i--) {
+        const trimmed = lines[i].trim();
+        if (trimmed !== '' && trimmed !== '{') {
+            lastIdx = i;
+            break;
+        }
+    }
+    const indent = lastIdx === -1 ? '  ' : baseIndentOfLastElement(lines, lastIdx) || '  ';
+    // Insert the new field immediately before the closing brace.
+    lines.splice(braceIdx, 0, `${indent}${normalizedClause};`);
+    return lines.join('\n');
+}
+/**
+ * Resolve the behavior entity body span (bodyOpen..bodyClose) for the chosen
+ * behavior, and REPORT the implementation keyword and resolved alias. Shared by
+ * insertBdefField, insertBdefClause, and resolveBehaviorAlias. Fail-safe:
+ * refuses ambiguity and a missing body.
+ *
+ * IMPORTANT (extensibility seam, spec §9): this resolver does NOT refuse
+ * unmanaged — it returns `implKeyword` and the CALLERS enforce the managed-only
+ * policy. A future unmanaged/saver capability flips that caller policy without
+ * touching this shared helper. (Extracted from insertBdefField — existing
+ * insertBdefField tests guard the refactor.)
+ */
+function resolveBehaviorEntityBody(lines, alias) {
+    const behaviors = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/\bdefine\s+behavior\s+for\s+\S+\s+alias\s+(\w+)/i);
+        if (m)
+            behaviors.push({ lineIdx: i, alias: m[1] });
+    }
+    if (behaviors.length === 0) {
+        throw new Error('no "define behavior … alias …" found in the source');
+    }
+    let chosen;
+    if (alias) {
+        const wanted = alias.toLowerCase();
+        const match = behaviors.find((b) => b.alias.toLowerCase() === wanted);
+        if (!match)
+            throw new Error(`alias '${alias}' not found among the defined behaviors`);
+        chosen = match;
+    }
+    else if (behaviors.length === 1) {
+        chosen = behaviors[0];
+    }
+    else {
+        throw new Error('multiple behaviors; specify alias');
+    }
+    let implKeyword = null;
+    for (let i = chosen.lineIdx; i >= 0; i--) {
+        const m = lines[i].match(/\b(managed|unmanaged)\s+implementation\s+in\s+class\b/i);
+        if (m) {
+            implKeyword = m[1].toLowerCase();
+            break;
+        }
+    }
+    let bodyOpen = -1;
+    for (let i = chosen.lineIdx; i < lines.length; i++) {
+        if (lines[i].includes('{')) {
+            bodyOpen = i;
+            break;
+        }
+    }
+    if (bodyOpen === -1)
+        throw new Error(`no body '{' found for alias ${chosen.alias}`);
+    const bodyClose = matchingClose(lines, bodyOpen);
+    if (bodyClose === -1)
+        throw new Error(`no matching '}' found for alias ${chosen.alias}`);
+    return { bodyOpen, bodyClose, implKeyword, alias: chosen.alias };
+}
+/**
+ * Resolve the effective BDEF entity alias for a given source string: auto-picks
+ * the single behavior when no alias is given, inheriting the same ambiguity /
+ * not-found / no-behavior errors from resolveBehaviorEntityBody. Intended as the
+ * thin alias-resolution entry point for handleBdefStub (I-A).
+ */
+export function resolveBehaviorAlias(source, alias) {
+    return resolveBehaviorEntityBody(source.split('\n'), alias).alias;
+}
+/**
+ * Add a `field ( … )` declaration or a mapping line to a MANAGED RAP behavior
+ * definition (B2a — the final leg of the table→CDS→BDEF chain).
+ *
+ * No DSL parser is used. The behavior entity body and the mapping block are
+ * located by their textual braces using simple `{`/`}` counting (BDEF rarely
+ * carries braces inside strings, so raw counting is sufficient and far safer
+ * than a half-built parser). Every other byte is left untouched.
+ *
+ * Fail-safe by design:
+ *  - Refuses (throws) an UNMANAGED implementation — only managed BDEF is
+ *    supported (the chain auto-persists; unmanaged needs hand-written savers).
+ *  - When several behaviors exist and no `alias` is given, throws rather than
+ *    guessing which entity to extend; throws too if a requested alias is absent.
+ *  - target 'mapping' with no mapping block throws rather than silently adding
+ *    nothing.
+ *
+ * @param source full managed BDEF source
+ * @param opts.alias  the entity alias to extend (`alias <ALIAS>`); optional only
+ *                    when exactly one behavior is defined
+ * @param opts.target 'field' → add a `field ( … ) Name;` to the entity body;
+ *                    'mapping' → add `Name = column;` to the entity's mapping block
+ * @param opts.clause the declaration WITHOUT a trailing `;`. For 'field', the
+ *                    full `field ( readonly ) Reference`; for 'mapping', the
+ *                    assignment `Reference = reference`. Exactly one `;` is
+ *                    re-applied.
+ * @returns the modified source
+ */
+export function insertBdefField(source, opts) {
+    const lines = source.split('\n');
+    // Normalize the clause: strip trailing whitespace + one trailing ';'.
+    const clause = opts.clause.replace(/\s+$/, '').replace(/;$/, '').replace(/\s+$/, '');
+    // 1–3. Resolve behavior entity body via shared helper; enforce managed-only
+    //      at this call site (caller policy per spec §9 extensibility seam).
+    const { bodyOpen, bodyClose, implKeyword } = resolveBehaviorEntityBody(lines, opts.alias);
+    if (implKeyword === 'unmanaged') {
+        throw new Error('insertBdefField: unmanaged BDEF not supported (managed only)');
+    }
+    if (opts.target === 'field') {
+        // 4. Insert after the LAST `field (` line inside the body; else just
+        //    before bodyClose at the body indent.
+        let lastFieldIdx = -1;
+        for (let i = bodyOpen + 1; i < bodyClose; i++) {
+            if (/^\s*field\s*\(/.test(lines[i]))
+                lastFieldIdx = i;
+        }
+        if (lastFieldIdx !== -1) {
+            const indent = (lines[lastFieldIdx].match(/^\s*/) ?? [''])[0];
+            lines.splice(lastFieldIdx + 1, 0, `${indent}${clause};`);
+        }
+        else {
+            const indent = bodyIndent(lines, bodyOpen, bodyClose);
+            lines.splice(bodyClose, 0, `${indent}${clause};`);
+        }
+        return lines.join('\n');
+    }
+    // 5. target 'mapping': find a `mapping for …` line inside the body, then its
+    //    block braces, and insert before the mapping block's close.
+    let mappingLineIdx = -1;
+    for (let i = bodyOpen + 1; i < bodyClose; i++) {
+        if (/^\s*mapping\s+for\b/.test(lines[i])) {
+            mappingLineIdx = i;
+            break;
+        }
+    }
+    if (mappingLineIdx === -1) {
+        throw new Error(`insertBdefField: no mapping block found for alias ${opts.alias ?? '(single)'}`);
+    }
+    let mapOpen = -1;
+    for (let i = mappingLineIdx; i < bodyClose; i++) {
+        if (lines[i].includes('{')) {
+            mapOpen = i;
+            break;
+        }
+    }
+    if (mapOpen === -1) {
+        throw new Error(`insertBdefField: no mapping block found for alias ${opts.alias ?? '(single)'}`);
+    }
+    const mapClose = matchingClose(lines, mapOpen);
+    if (mapClose === -1) {
+        throw new Error(`insertBdefField: no matching '}' for the mapping block of alias ${opts.alias ?? '(single)'}`);
+    }
+    // Indent from an existing mapping entry; default to the mapping line's
+    // indent + 2 spaces.
+    let mapEntryIndent = null;
+    for (let i = mapOpen + 1; i < mapClose; i++) {
+        if (lines[i].trim() !== '') {
+            mapEntryIndent = (lines[i].match(/^\s*/) ?? [''])[0];
+            break;
+        }
+    }
+    if (mapEntryIndent === null) {
+        const mapLineIndent = (lines[mappingLineIdx].match(/^\s*/) ?? [''])[0];
+        mapEntryIndent = `${mapLineIndent}  `;
+    }
+    lines.splice(mapClose, 0, `${mapEntryIndent}${clause};`);
+    return lines.join('\n');
+}
+/**
+ * Insert a complete BDEF clause line (a validation/determination/action built
+ * by buildClauseLine) into the chosen MANAGED entity body, immediately before
+ * the body's closing brace, at the body indentation. Managed-only policy is
+ * enforced HERE (the caller), not in the shared resolver (spec §9). See §4.1.
+ */
+export function insertBdefClause(source, opts) {
+    const lines = source.split('\n');
+    const { bodyOpen, bodyClose, implKeyword } = resolveBehaviorEntityBody(lines, opts.alias);
+    if (implKeyword === 'unmanaged') {
+        throw new Error('insertBdefClause: unmanaged BDEF not supported (managed only)');
+    }
+    const indent = bodyIndent(lines, bodyOpen, bodyClose);
+    lines.splice(bodyClose, 0, `${indent}${opts.clauseLine}`);
+    return lines.join('\n');
+}
+/**
+ * Index of the line carrying the '}' that matches the FIRST '{' on line
+ * `openIdx`, counting '{'/'}' across all lines (raw count — BDEF rarely has
+ * braces inside string literals). Returns -1 if unbalanced.
+ */
+function matchingClose(lines, openIdx) {
+    let depth = 0;
+    let seenOpen = false;
+    for (let i = openIdx; i < lines.length; i++) {
+        for (const ch of lines[i]) {
+            if (ch === '{') {
+                depth++;
+                seenOpen = true;
+            }
+            else if (ch === '}') {
+                depth--;
+                if (seenOpen && depth === 0)
+                    return i;
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * Indentation to use for a new line inside an entity body that has no `field (`
+ * anchor: derived from the first non-empty body line, else the body-open
+ * line's indent + 2 spaces.
+ */
+function bodyIndent(lines, bodyOpen, bodyClose) {
+    for (let i = bodyOpen + 1; i < bodyClose; i++) {
+        if (lines[i].trim() !== '')
+            return (lines[i].match(/^\s*/) ?? [''])[0];
+    }
+    const openIndent = (lines[bodyOpen].match(/^\s*/) ?? [''])[0];
+    return `${openIndent}  `;
+}
+function stubImpl(name, extraComment) {
+    const body = extraComment
+        ? `  " TODO: implement business logic — use /abap-eml\n  " ${extraComment}`
+        : '  " TODO: implement business logic — use /abap-eml';
+    return `METHOD ${name}.\n${body}\nENDMETHOD.`;
+}
+/**
+ * Build the CCIMP handler method (declaration + empty implementation) for a
+ * stub. Signatures verified against ABAP keyword docs ABAPHANDLER_METH_MODIFY
+ * (action: REQUEST is optional; the input parameter is delivered via
+ * keys-%param). `<Entity>` is the BDEF alias. See spec §4.1.
+ */
+export function buildHandlerMethod(kind, opts) {
+    const e = opts.entity;
+    if (kind === 'validation') {
+        return {
+            decl: `METHODS ${opts.name} FOR VALIDATE ON SAVE IMPORTING keys FOR ${e}~${opts.name}.`,
+            impl: stubImpl(opts.name),
+        };
+    }
+    if (kind === 'determination') {
+        const on = opts.trigger === 'save' ? 'SAVE' : 'MODIFY';
+        return {
+            decl: `METHODS ${opts.name} FOR DETERMINE ON ${on} IMPORTING keys FOR ${e}~${opts.name}.`,
+            impl: stubImpl(opts.name),
+        };
+    }
+    // action
+    const resultClause = opts.result ? ' RESULT result' : '';
+    const method = {
+        decl: `METHODS ${opts.name} FOR MODIFY IMPORTING keys FOR ACTION ${e}~${opts.name}${resultClause}.`,
+        impl: stubImpl(opts.name, opts.parameter ? 'input parameter is in keys-%param' : undefined),
+    };
+    if (opts.features) {
+        method.featuresDecl = `METHODS get_instance_features FOR INSTANCE FEATURES IMPORTING keys REQUEST requested_features FOR ${e} RESULT result.`;
+        method.featuresImpl = `METHOD get_instance_features.\n  " TODO: populate result with the %action-${opts.name} enabled-state — use /abap-eml\nENDMETHOD.`;
+    }
+    return method;
+}
+/** True if the line is a full-line ABAP comment (`*` in col 1) — skipped when scanning. */
+function isCommentLine(line) {
+    return /^\s*\*/.test(line) || line.trimStart().startsWith('"');
+}
+/**
+ * Locate a named local class's DEFINITION and IMPLEMENTATION spans by ABAP
+ * keyword matching (NOT brace counting — ABAP classes have no braces, so the
+ * B2a `matchingClose` primitive does not apply). Case-insensitive; skips
+ * full-line comments; tolerant of multiple classes in one CCIMP include.
+ * Returns null if either block is missing. See spec §4.1 (review C4).
+ */
+export function classBlockSpan(lines, className) {
+    const name = className.toLowerCase();
+    const defRe = new RegExp(`^\\s*class\\s+${name}\\s+definition\\b`, 'i');
+    const implRe = new RegExp(`^\\s*class\\s+${name}\\s+implementation\\b`, 'i');
+    const endRe = /^\s*endclass\s*\./i;
+    const findBlock = (headerRe) => {
+        for (let i = 0; i < lines.length; i++) {
+            if (isCommentLine(lines[i]))
+                continue;
+            if (headerRe.test(lines[i])) {
+                for (let j = i + 1; j < lines.length; j++) {
+                    if (isCommentLine(lines[j]))
+                        continue;
+                    if (endRe.test(lines[j]))
+                        return { start: i, end: j };
+                }
+                return null; // header without ENDCLASS
+            }
+        }
+        return null;
+    };
+    const def = findBlock(defRe);
+    const impl = findBlock(implRe);
+    if (!def || !impl)
+        return null;
+    return { defStart: def.start, defEnd: def.end, implStart: impl.start, implEnd: impl.end };
+}
+/** The method name a `METHODS <name> …` declaration line declares (lowercased), or null. */
+function declaredMethodName(declLine) {
+    const m = declLine.match(/^\s*methods\s+(\w+)/i);
+    return m ? m[1].toLowerCase() : null;
+}
+/** Apply a base indent to every non-empty line of a multi-line block. */
+function indentBlock(block, indent) {
+    return block
+        .split('\n')
+        .map((l) => (l === '' ? '' : `${indent}${l}`))
+        .join('\n');
+}
+/**
+ * Insert a handler method (decl into PRIVATE/PROTECTED SECTION, impl before
+ * the IMPLEMENTATION ENDCLASS) into an EXISTING lhc_<entity> class, scoped via
+ * classBlockSpan. Idempotent (refuses a duplicate method name). For a
+ * feature-controlled action, also inserts the get_instance_features pair, but
+ * only if that method is not already present. See spec §4.1 / §4.4.
+ */
+export function insertHandlerMethod(ccimp, opts) {
+    const className = `lhc_${opts.entity.toLowerCase()}`;
+    const lines = ccimp.split('\n');
+    const span = classBlockSpan(lines, className);
+    if (!span)
+        throw new Error(`insertHandlerMethod: no ${className} class found — create a skeleton instead`);
+    const { method } = opts;
+    // Existing method names within the definition span (idempotency).
+    const existingNames = new Set();
+    for (let i = span.defStart; i <= span.defEnd; i++) {
+        const n = declaredMethodName(lines[i]);
+        if (n)
+            existingNames.add(n);
+    }
+    const newName = declaredMethodName(method.decl);
+    if (newName && existingNames.has(newName)) {
+        throw new Error(`insertHandlerMethod: method '${newName}' already exists in ${className}`);
+    }
+    // Locate the visibility section header inside the definition span.
+    let sectionIdx = -1;
+    for (let i = span.defStart + 1; i < span.defEnd; i++) {
+        if (/^\s*(private|protected)\s+section\s*\./i.test(lines[i])) {
+            sectionIdx = i;
+            break;
+        }
+    }
+    if (sectionIdx === -1) {
+        throw new Error(`insertHandlerMethod: no PRIVATE/PROTECTED SECTION found in ${className}`);
+    }
+    // Indents: decl one level under the section header; impl one level under the class.
+    const sectionIndent = (lines[sectionIdx].match(/^\s*/) ?? [''])[0];
+    const declIndent = `${sectionIndent}  `;
+    const implIndent = ((lines[span.implStart].match(/^\s*/) ?? [''])[0]) + '  ';
+    const wantFeatures = !!(method.featuresDecl && method.featuresImpl && !existingNames.has('get_instance_features'));
+    // Insert IMPL side first (higher line indices) so DEFINITION inserts don't shift implEnd.
+    const implInserts = [];
+    implInserts.push(indentBlock(method.impl, implIndent));
+    if (wantFeatures)
+        implInserts.push(indentBlock(method.featuresImpl, implIndent));
+    lines.splice(span.implEnd, 0, ...implInserts);
+    // Insert DEFINITION side (decl right after the section header).
+    const declInserts = [`${declIndent}${method.decl}`];
+    if (wantFeatures)
+        declInserts.push(`${declIndent}${method.featuresDecl}`);
+    lines.splice(sectionIdx + 1, 0, ...declInserts);
+    return lines.join('\n');
+}
+/**
+ * Create a new lhc_<entity> behavior handler class (DEFINITION + IMPLEMENTATION)
+ * appended to the CCIMP source, when none exists yet (a plain CRUD managed stack
+ * has no handler class until the first augmentation). Refuses if the class is
+ * already present. See spec §4.1 / §4.4 (review C3).
+ */
+export function createHandlerClassSkeleton(ccimp, opts) {
+    const className = `lhc_${opts.entity.toLowerCase()}`;
+    if (classBlockSpan(ccimp.split('\n'), className)) {
+        throw new Error(`createHandlerClassSkeleton: ${className} already exists — use insertHandlerMethod`);
+    }
+    const { method } = opts;
+    const defLines = [
+        `CLASS ${className} DEFINITION INHERITING FROM cl_abap_behavior_handler.`,
+        '  PRIVATE SECTION.',
+        `    ${method.decl}`,
+    ];
+    if (method.featuresDecl)
+        defLines.push(`    ${method.featuresDecl}`);
+    defLines.push('ENDCLASS.');
+    const implLines = [`CLASS ${className} IMPLEMENTATION.`, indentBlock(method.impl, '  ')];
+    if (method.featuresImpl)
+        implLines.push(indentBlock(method.featuresImpl, '  '));
+    implLines.push('ENDCLASS.');
+    const skeleton = [...defLines, '', ...implLines].join('\n');
+    const trimmed = ccimp.replace(/\s+$/, '');
+    return trimmed === '' ? skeleton : `${trimmed}\n\n${skeleton}`;
+}
+/**
+ * Insert a `use <clause>;` line (e.g. `use action Approve;`) into a PROJECTION
+ * behavior definition's entity body, before its closing brace. Projection BDEFs
+ * carry a top-level `projection;`; this refuses anything else (a base/managed
+ * BDEF uses `field`/`validation`/… not `use`). Idempotent: refuses if the same
+ * `use <clause>;` is already present. See spec §4.4.
+ */
+export function insertProjectionUse(source, opts) {
+    if (!/^\s*projection\s*;/m.test(source)) {
+        throw new Error('insertProjectionUse: not a projection BDEF (no top-level `projection;`)');
+    }
+    const lines = source.split('\n');
+    const { bodyOpen, bodyClose } = resolveBehaviorEntityBody(lines, opts.alias);
+    const useLine = `use ${opts.useClause.replace(/^use\s+/i, '').replace(/;\s*$/, '')}`;
+    // Idempotency by NAME, not exact line (review I3): a grouped or
+    // feature-qualified `use ( … ) action Approve;` must still count as present.
+    // Match the trailing identifier of the clause (e.g. 'Approve' in 'action Approve').
+    const nameMatch = opts.useClause.match(/(\w+)\s*;?\s*$/);
+    const name = nameMatch ? nameMatch[1] : null;
+    if (name) {
+        // Case-SENSITIVE name match (SC-6): RAP action names are PascalCase (e.g. 'Delete'),
+        // while CRUD keywords are lowercase ('delete'). A case-insensitive flag would
+        // false-positive `use action Delete;` against an existing `use delete;`.
+        const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const dupRe = new RegExp(`\\buse\\b.*\\b${escapedName}\\b`);
+        for (let i = bodyOpen + 1; i < bodyClose; i++) {
+            if (dupRe.test(lines[i])) {
+                throw new Error(`insertProjectionUse: a 'use … ${name}' is already present in the projection body`);
+            }
+        }
+    }
+    const indent = bodyIndent(lines, bodyOpen, bodyClose);
+    lines.splice(bodyClose, 0, `${indent}${useLine};`);
+    return lines.join('\n');
+}
+/**
+ * Insert an FE action-button annotation above an existing field in a DDLX
+ * metadata extension (or projection @UI). Form (doc-verified vs the SAP Fiori
+ * feature showcase): `@UI.lineItem: [{ type: #FOR_ACTION, dataAction: '<a>',
+ * label: '<l>', position: <p> }]` on a property — the button renders in the
+ * table toolbar. Idempotent: refuses if a lineItem with the same dataAction is
+ * already present. See spec §4.4.
+ */
+export function insertMdeActionButton(source, opts) {
+    const label = opts.label ?? opts.action;
+    const position = typeof opts.position === 'number' ? opts.position : 10;
+    // Idempotency: refuse a second FOR_ACTION lineItem for the same action.
+    // Escape the action name (defensive — ABAP names are \w+, but never build a
+    // RegExp from an unescaped input).
+    const esc = opts.action.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (new RegExp(`dataAction:\\s*'${esc}'`).test(source)) {
+        throw new Error(`insertMdeActionButton: an action button for '${opts.action}' already exists`);
+    }
+    const lines = source.split('\n');
+    // Anchor: the field's own declaration line (`<field>;` or `<field>`), matched
+    // like promoteCdsFieldToLineItem's bare-name rule.
+    let defIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const t = lines[i].trim().replace(/;$/, '').trim();
+        if (t === opts.anchorField) {
+            defIdx = i;
+            break;
+        }
+    }
+    if (defIdx === -1) {
+        throw new Error(`insertMdeActionButton: anchor field '${opts.anchorField}' not found in the metadata extension`);
+    }
+    // Walk up past lines that start with '@' to find the top of the annotation block.
+    let blockStart = defIdx;
+    while (blockStart > 0 && lines[blockStart - 1].trim().startsWith('@'))
+        blockStart--;
+    const indent = (lines[defIdx].match(/^\s*/) ?? [''])[0];
+    // If the annotation block already contains a @UI.lineItem, MERGE the FOR_ACTION
+    // entry as the first element of that existing array (one @UI.lineItem per element).
+    // Otherwise, insert a standalone @UI.lineItem line above the block.
+    let existingLineItemIdx = -1;
+    for (let i = blockStart; i < defIdx; i++) {
+        if (/@UI\.lineItem\b/.test(lines[i])) {
+            existingLineItemIdx = i;
+            break;
+        }
+    }
+    if (existingLineItemIdx !== -1) {
+        // Find the first '[' on or after the @UI.lineItem line and insert the FOR_ACTION
+        // object immediately after it.
+        const lineItemLine = lines[existingLineItemIdx];
+        const bracketPos = lineItemLine.indexOf('[');
+        if (bracketPos === -1) {
+            // Malformed — fall through to standalone insert (defensive)
+            const ann = `${indent}@UI.lineItem: [{ type: #FOR_ACTION, dataAction: '${opts.action}', label: '${label}', position: ${position} }]`;
+            lines.splice(blockStart, 0, ann);
+        }
+        else {
+            const forActionEntry = `{ type: #FOR_ACTION, dataAction: '${opts.action}', label: '${label}', position: ${position} }, `;
+            lines[existingLineItemIdx] =
+                lineItemLine.slice(0, bracketPos + 1) + forActionEntry + lineItemLine.slice(bracketPos + 1);
+        }
+    }
+    else {
+        // Standalone: insert a new @UI.lineItem line above the annotation block.
+        const ann = `${indent}@UI.lineItem: [{ type: #FOR_ACTION, dataAction: '${opts.action}', label: '${label}', position: ${position} }]`;
+        lines.splice(blockStart, 0, ann);
+    }
+    return lines.join('\n');
+}
+/**
+ * Insert a view-level `@UI.headerInfo: { … }` block into a DDLX metadata
+ * extension, ABOVE the `annotate view … with` line — header annotations sit on
+ * the view, not on a field. This drives the Fiori Elements Object Page header
+ * (object type name + title/description).
+ *
+ * Pure string splice — no CDS parser. The anchor is the textual `annotate view`
+ * line; the block is inserted at that line's indentation immediately above it.
+ *
+ * Fail-safe by design:
+ *  - Idempotent: refuses (throws /already/) when a `@UI.headerInfo` already
+ *    exists anywhere in the source — a metadata extension has exactly one.
+ *  - Throws, naming the anchor, when no `annotate view` line is found.
+ *
+ * @param source full DDLX metadata-extension source
+ * @param opts.typeName        the singular object type name (e.g. 'Maintenance Request')
+ * @param opts.typeNamePlural  the plural object type name
+ * @param opts.titleField      the field whose value renders as the header title
+ * @param opts.descriptionField optional field for the header description line
+ * @returns the modified source
+ */
+export function insertDdlxHeaderInfo(source, opts) {
+    // Idempotency: a metadata extension carries exactly one headerInfo block.
+    if (/@UI\.headerInfo\b/.test(source)) {
+        throw new Error('insertDdlxHeaderInfo: a @UI.headerInfo block already exists (idempotent refusal)');
+    }
+    const lines = source.split('\n');
+    // Anchor: the `annotate view … with` line — header annotations sit above it.
+    let annotateIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/\bannotate\s+view\b/.test(lines[i])) {
+            annotateIdx = i;
+            break;
+        }
+    }
+    if (annotateIdx === -1) {
+        throw new Error('insertDdlxHeaderInfo: no "annotate view" line found (header annotations sit on the view)');
+    }
+    const indent = (lines[annotateIdx].match(/^\s*/) ?? [''])[0];
+    const block = [
+        `${indent}@UI.headerInfo: {`,
+        `${indent}  typeName: '${opts.typeName}',`,
+        `${indent}  typeNamePlural: '${opts.typeNamePlural}',`,
+    ];
+    if (opts.descriptionField) {
+        block.push(`${indent}  title: { type: #STANDARD, value: '${opts.titleField}' },`);
+        block.push(`${indent}  description: { type: #STANDARD, value: '${opts.descriptionField}' }`);
+    }
+    else {
+        block.push(`${indent}  title: { type: #STANDARD, value: '${opts.titleField}' }`);
+    }
+    block.push(`${indent}}`);
+    lines.splice(annotateIdx, 0, ...block);
+    return lines.join('\n');
+}
+/**
+ * Add a `@UI.selectionField: [{ position: N }]` annotation to a DDLX metadata
+ * extension so the field appears as a filter-bar entry in a Fiori Elements List
+ * Report. Dual behaviour, mirroring the lineItem kinds:
+ *  - In-place (like {@link insertMdeActionButton}'s anchor / the
+ *    {@link promoteCdsFieldToLineItem} promotion): when the field is already
+ *    exposed in the annotate body, insert the annotation directly above the
+ *    field's declaration line at the same indentation.
+ *  - Append (like {@link insertDdlxLineItem}): when the field is not yet present,
+ *    append `@UI.selectionField …` + `<field>;` before the body's closing brace.
+ *
+ * Pure string splice — no CDS parser. Throws, naming the closing-brace anchor,
+ * when the field is absent AND no closing brace can be found.
+ *
+ * @param source full DDLX metadata-extension source
+ * @param opts.field    the field name to expose as a filter
+ * @param opts.position the `@UI.selectionField` position (filter order)
+ * @returns the modified source
+ */
+export function insertDdlxSelectionField(source, opts) {
+    const lines = source.split('\n');
+    // In-place: locate the field's own declaration line (`<field>;` or `<field>`).
+    let defIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const t = lines[i].trim().replace(/;$/, '').trim();
+        if (t === opts.field) {
+            defIdx = i;
+            break;
+        }
+    }
+    if (defIdx !== -1) {
+        const indent = (lines[defIdx].match(/^\s*/) ?? [''])[0];
+        lines.splice(defIdx, 0, `${indent}@UI.selectionField: [{ position: ${opts.position} }]`);
+        return lines.join('\n');
+    }
+    // Append: before the body's closing brace (mirror insertDdlxLineItem),
+    // routed through the shared appendAnchor resolver.
+    const { braceIdx, indent } = appendAnchor(lines, 'insertDdlxSelectionField');
+    lines.splice(braceIdx, 0, `${indent}@UI.selectionField: [{ position: ${opts.position} }]`, `${indent}${opts.field};`);
+    return lines.join('\n');
+}
+/**
+ * Add a `@UI.identification` annotation to a DDLX metadata extension. Two modes:
+ *  - Plain (field given, no forAction): `@UI.identification: [{ position: N }]`
+ *    inserted directly above the field's declaration line (Object Page field
+ *    section) — same in-place anchor as {@link insertDdlxSelectionField}.
+ *  - FOR_ACTION button (forAction set): `@UI.identification: [{ type: #FOR_ACTION,
+ *    dataAction: '<a>', label: '<l>', position: N }]` — the Object-Page action
+ *    button (lifts the out-of-scope note in SKILL.md). Anchored above `field`
+ *    when given, else appended before the body's closing brace.
+ *
+ * Idempotency (mirrors the lineItem FOR_ACTION refuse logic): refuses (throws
+ * /duplicate/) when an existing `@UI.identification` already carries the same
+ * `dataAction`. Throws, naming the closing-brace anchor, when appending with no
+ * closing brace, or (plain mode) when the field cannot be located.
+ *
+ * @param source full DDLX metadata-extension source
+ * @param opts.field     the field to annotate (required for plain mode; optional
+ *                       anchor for a FOR_ACTION button)
+ * @param opts.position  the `@UI.identification` position
+ * @param opts.forAction FOR_ACTION button descriptor { dataAction, label }
+ * @returns the modified source
+ */
+export function insertDdlxIdentification(source, opts) {
+    const lines = source.split('\n');
+    if (opts.forAction) {
+        const { dataAction, label } = opts.forAction;
+        // A #FOR_ACTION @UI.identification is ELEMENT-ATTACHED: a target field is
+        // REQUIRED. A lone annotation before the closing brace is invalid DDLX and
+        // fails activation — so, exactly like insertMdeActionButton's mandatory
+        // anchor field, the button piggybacks on an existing element line.
+        if (!opts.field) {
+            throw new Error('insertDdlxIdentification: forAction requires a target field to attach the button to');
+        }
+        // Idempotency: refuse a duplicate dataAction within ANY existing
+        // @UI.identification array — whole-source, bracket-balanced, so a duplicate
+        // inside a multi-line hand-authored array is caught, not just same-line.
+        if (identificationHasDataAction(source, dataAction)) {
+            throw new Error(`insertDdlxIdentification: an identification button for dataAction '${dataAction}' already exists (duplicate)`);
+        }
+        const defIdx = findFieldLine(lines, opts.field);
+        if (defIdx === -1) {
+            throw new Error(`insertDdlxIdentification: anchor field '${opts.field}' not found in the metadata extension`);
+        }
+        const indent = (lines[defIdx].match(/^\s*/) ?? [''])[0];
+        lines.splice(defIdx, 0, `${indent}@UI.identification: [{ type: #FOR_ACTION, dataAction: '${dataAction}', label: '${label}', position: ${opts.position} }]`);
+        return lines.join('\n');
+    }
+    // Plain identification is also element-attached — a field is required.
+    if (!opts.field) {
+        throw new Error('insertDdlxIdentification: field is required for a plain @UI.identification');
+    }
+    const defIdx = findFieldLine(lines, opts.field);
+    if (defIdx === -1) {
+        throw new Error(`insertDdlxIdentification: field '${opts.field}' not found in the metadata extension`);
+    }
+    const indent = (lines[defIdx].match(/^\s*/) ?? [''])[0];
+    lines.splice(defIdx, 0, `${indent}@UI.identification: [{ position: ${opts.position} }]`);
+    return lines.join('\n');
+}
+/**
+ * True if any `@UI.identification: [ … ]` array in the source already carries
+ * the given `dataAction`. Scans the whole source and balances the array's
+ * brackets, so a duplicate inside a MULTI-LINE hand-authored identification
+ * array is caught — not just a same-line occurrence.
+ */
+function identificationHasDataAction(source, dataAction) {
+    const esc = dataAction.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const dupRe = new RegExp(`dataAction:\\s*'${esc}'`);
+    const marker = '@UI.identification';
+    let idx = source.indexOf(marker);
+    while (idx !== -1) {
+        const bracket = source.indexOf('[', idx);
+        if (bracket === -1)
+            break;
+        // Balance '['/']' from the array's opening bracket to find its end.
+        let depth = 0;
+        let end = source.length - 1;
+        for (let i = bracket; i < source.length; i++) {
+            const ch = source[i];
+            if (ch === '[')
+                depth++;
+            else if (ch === ']') {
+                depth--;
+                if (depth === 0) {
+                    end = i;
+                    break;
+                }
+            }
+        }
+        if (dupRe.test(source.slice(bracket, end + 1)))
+            return true;
+        idx = source.indexOf(marker, end + 1);
+    }
+    return false;
+}
+/** Index of a field's own declaration line (`<field>;` or `<field>`), or -1. */
+function findFieldLine(lines, field) {
+    for (let i = 0; i < lines.length; i++) {
+        const t = lines[i].trim().replace(/;$/, '').trim();
+        if (t === field)
+            return i;
+    }
+    return -1;
+}
+/**
+ * Resolve the "append before the closing brace" anchor for a DDLX annotate
+ * body: the last line that is just `}`, plus the indentation of the last entry
+ * (default 2 spaces). Throws, naming the anchor, when no closing brace exists.
+ */
+function appendAnchor(lines, who) {
+    let braceIdx = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (lines[i].trim() === '}') {
+            braceIdx = i;
+            break;
+        }
+    }
+    if (braceIdx === -1) {
+        throw new Error(`${who}: no closing brace found for the annotate body`);
+    }
+    let lastIdx = -1;
+    for (let i = braceIdx - 1; i >= 0; i--) {
+        const trimmed = lines[i].trim();
+        if (trimmed !== '' && trimmed !== '{') {
+            lastIdx = i;
+            break;
+        }
+    }
+    const indent = lastIdx === -1 ? '  ' : baseIndentOfLastElement(lines, lastIdx) || '  ';
+    return { braceIdx, indent };
+}
+/**
+ * True if any array of the given view-level annotation (`marker`, e.g.
+ * `@UI.facet` / `@UI.chart`) satisfies `predicate` on its bracket-balanced
+ * array text. Scans the whole source and balances the array's `[`/`]`, so a
+ * match inside a MULTI-LINE array is caught, not just a same-line one. Mirrors
+ * the scanning shape of {@link identificationHasDataAction} but generalised
+ * over the marker and the per-array test.
+ */
+function annotationArrayMatches(source, marker, predicate) {
+    let idx = source.indexOf(marker);
+    while (idx !== -1) {
+        const bracket = source.indexOf('[', idx);
+        if (bracket === -1)
+            break;
+        let depth = 0;
+        let end = source.length - 1;
+        for (let i = bracket; i < source.length; i++) {
+            const ch = source[i];
+            if (ch === '[')
+                depth++;
+            else if (ch === ']') {
+                depth--;
+                if (depth === 0) {
+                    end = i;
+                    break;
+                }
+            }
+        }
+        if (predicate(source.slice(bracket, end + 1)))
+            return true;
+        idx = source.indexOf(marker, end + 1);
+    }
+    return false;
+}
+/** Index of the `annotate view … with` line, or -1. */
+function findAnnotateViewLine(lines) {
+    for (let i = 0; i < lines.length; i++) {
+        if (/\bannotate\s+view\b/.test(lines[i]))
+            return i;
+    }
+    return -1;
+}
+/**
+ * Add a `@UI.fieldGroup: [{ qualifier: '<q>', position: N }]` annotation to a
+ * DDLX metadata extension for a single field — the same dual behaviour as
+ * {@link insertDdlxSelectionField}: in-place above the field's declaration when
+ * it is already exposed, else append the field + annotation before the body's
+ * closing brace. Shared by {@link insertDdlxFacet}.
+ */
+function insertDdlxFieldGroup(source, qualifier, field, position) {
+    const lines = source.split('\n');
+    const ann = `@UI.fieldGroup: [{ qualifier: '${qualifier}', position: ${position} }]`;
+    const defIdx = findFieldLine(lines, field);
+    if (defIdx !== -1) {
+        const indent = (lines[defIdx].match(/^\s*/) ?? [''])[0];
+        lines.splice(defIdx, 0, `${indent}${ann}`);
+        return lines.join('\n');
+    }
+    const { braceIdx, indent } = appendAnchor(lines, 'insertDdlxFacet');
+    lines.splice(braceIdx, 0, `${indent}${ann}`, `${indent}${field};`);
+    return lines.join('\n');
+}
+/**
+ * Add a Fiori Elements collection facet to a DDLX metadata extension, in two
+ * coordinated parts:
+ *  1. ONE view-level `@UI.facet` entry (a `#FIELDGROUP_REFERENCE`) above the
+ *     `annotate view` line. If a `@UI.facet: [ … ]` array already exists, the new
+ *     entry is MERGED into it (one array of facets); otherwise a fresh
+ *     `@UI.facet: [ … ]` line is inserted.
+ *  2. A per-field `@UI.fieldGroup: [{ qualifier: '<fieldGroupQualifier>',
+ *     position: N }]` on EACH named field — in-place above the field when it is
+ *     already exposed, else appended (same dual behaviour as
+ *     {@link insertDdlxSelectionField}). The facet's `targetQualifier` binds to
+ *     the field group, so the Object Page renders the grouped fields under the
+ *     facet's label.
+ *
+ * Pure string splice — no CDS parser. Fail-safe by design:
+ *  - Idempotent as a unit on `facetId`: refuses (throws /already/) when a facet
+ *    with the same id is already present anywhere in the source, BEFORE any
+ *    field is touched — so a refused call is a true no-op.
+ *  - Throws, naming the anchor, when a fresh facet must be inserted but no
+ *    `annotate view` line exists.
+ */
+export function insertDdlxFacet(source, opts) {
+    // Idempotency (unit): refuse a duplicate facetId across any existing @UI.facet
+    // array before touching a single field.
+    const escId = opts.facetId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const idRe = new RegExp(`id:\\s*'${escId}'`);
+    if (annotationArrayMatches(source, '@UI.facet', (txt) => idRe.test(txt))) {
+        throw new Error(`insertDdlxFacet: a facet with id '${opts.facetId}' already exists (idempotent refusal)`);
+    }
+    const entry = `{ id: '${opts.facetId}', purpose: #STANDARD, type: #FIELDGROUP_REFERENCE, `
+        + `label: '${opts.label}', targetQualifier: '${opts.fieldGroupQualifier}', position: ${opts.position} }`;
+    // 1. View-level facet: merge into an existing @UI.facet array, else insert
+    //    a fresh line above `annotate view`.
+    let lines = source.split('\n');
+    let facetIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/@UI\.facet\b/.test(lines[i])) {
+            facetIdx = i;
+            break;
+        }
+    }
+    let merged = false;
+    if (facetIdx !== -1) {
+        const bracketPos = lines[facetIdx].indexOf('[');
+        if (bracketPos !== -1) {
+            lines[facetIdx] =
+                lines[facetIdx].slice(0, bracketPos + 1) + entry + ', ' + lines[facetIdx].slice(bracketPos + 1);
+            merged = true;
+        }
+        // Malformed (no '[' on the @UI.facet line) → fall through to a fresh insert.
+    }
+    if (!merged) {
+        const annotateIdx = findAnnotateViewLine(lines);
+        if (annotateIdx === -1) {
+            throw new Error('insertDdlxFacet: no "annotate view" line found (facet annotations sit on the view)');
+        }
+        const indent = (lines[annotateIdx].match(/^\s*/) ?? [''])[0];
+        lines.splice(annotateIdx, 0, `${indent}@UI.facet: [${entry}]`);
+    }
+    // 2. Per-field field groups (dual: in-place or append), re-splicing per field.
+    let out = lines.join('\n');
+    for (const f of opts.fields) {
+        out = insertDdlxFieldGroup(out, opts.fieldGroupQualifier, f.field, f.position);
+    }
+    return out;
+}
+/**
+ * Insert a `@UI.dataPoint: { title: '<title>' }` annotation above an EXISTING
+ * exposed field in a DDLX metadata extension (append `, criticality:
+ * '<criticalityField>'` when a criticality field is given). The data point is
+ * element-attached — the target field is required and must already be exposed;
+ * this transform does NOT create the criticality calculated field (that pairing
+ * is the skill's job via a prior `cds-field` insert).
+ *
+ * Pure string splice — no CDS parser. Throws, naming the field, when the target
+ * field is absent from the metadata extension.
+ *
+ * @param source full DDLX metadata-extension source
+ * @param opts.field            the field to annotate (required, must be present)
+ * @param opts.title            the data point title text
+ * @param opts.criticalityField optional field name driving the criticality colour
+ * @returns the modified source
+ */
+export function insertDdlxDataPoint(source, opts) {
+    const lines = source.split('\n');
+    const defIdx = findFieldLine(lines, opts.field);
+    if (defIdx === -1) {
+        throw new Error(`insertDdlxDataPoint: field '${opts.field}' not found in the metadata extension`);
+    }
+    const crit = opts.criticalityField ? `, criticality: '${opts.criticalityField}'` : '';
+    const indent = (lines[defIdx].match(/^\s*/) ?? [''])[0];
+    lines.splice(defIdx, 0, `${indent}@UI.dataPoint: { title: '${opts.title}'${crit} }`);
+    return lines.join('\n');
+}
+const CHART_TYPES = ['COLUMN', 'BAR', 'LINE', 'DONUT'];
+/**
+ * Insert a view-level `@UI.chart` AND its paired `@UI.presentationVariant`
+ * (`visualizations: [{ type: #AS_CHART … }]`) above the `annotate view` line of
+ * a DDLX metadata extension. ALP/OVP bind a chart through the presentation
+ * variant, never the raw chart — so BOTH are always emitted together, as a unit.
+ *
+ * Pure string splice — no CDS parser. Fail-safe by design:
+ *  - `chartType` must be one of COLUMN|BAR|LINE|DONUT and maps to the CDS enum
+ *    literal `#<TYPE>`; anything else throws.
+ *  - Idempotent as a unit on the qualifier: a named chart refuses (throws
+ *    /already/) when a `@UI.chart` with the same qualifier is present; an
+ *    anonymous chart (no qualifier) refuses when any anonymous `@UI.chart`
+ *    already exists.
+ *  - Throws, naming the anchor, when no `annotate view` line exists.
+ *
+ * @param source full DDLX metadata-extension source
+ * @param opts.qualifier  optional chart/presentation-variant qualifier (binds the pair)
+ * @param opts.chartType  COLUMN|BAR|LINE|DONUT → `#COLUMN`/`#BAR`/`#LINE`/`#DONUT`
+ * @param opts.dimensions dimension field names
+ * @param opts.measures   measure field names
+ * @returns the modified source
+ */
+export function insertDdlxChart(source, opts) {
+    if (!CHART_TYPES.includes(opts.chartType)) {
+        throw new Error(`insertDdlxChart: unknown chartType '${opts.chartType}' — expected COLUMN|BAR|LINE|DONUT`);
+    }
+    // Idempotency (unit): keyed on qualifier. A named chart matches on its
+    // qualifier; an anonymous chart matches any existing @UI.chart without one.
+    if (opts.qualifier) {
+        const escQ = opts.qualifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const qRe = new RegExp(`qualifier:\\s*'${escQ}'`);
+        if (annotationArrayMatches(source, '@UI.chart', (txt) => qRe.test(txt))) {
+            throw new Error(`insertDdlxChart: a chart with qualifier '${opts.qualifier}' already exists (idempotent refusal)`);
+        }
+    }
+    else if (annotationArrayMatches(source, '@UI.chart', (txt) => !/qualifier:/.test(txt))) {
+        throw new Error('insertDdlxChart: an anonymous @UI.chart already exists (idempotent refusal)');
+    }
+    const lines = source.split('\n');
+    const annotateIdx = findAnnotateViewLine(lines);
+    if (annotateIdx === -1) {
+        throw new Error('insertDdlxChart: no "annotate view" line found (chart annotations sit on the view)');
+    }
+    const indent = (lines[annotateIdx].match(/^\s*/) ?? [''])[0];
+    const dims = opts.dimensions.map((d) => `'${d}'`).join(', ');
+    const meas = opts.measures.map((m) => `'${m}'`).join(', ');
+    const chartQ = opts.qualifier ? `qualifier: '${opts.qualifier}', ` : '';
+    const chartLine = `${indent}@UI.chart: [{ ${chartQ}chartType: #${opts.chartType}, `
+        + `dimensions: [${dims}], measures: [${meas}] }]`;
+    const pvQ = opts.qualifier ? `, qualifier: '${opts.qualifier}'` : '';
+    const pvLine = `${indent}@UI.presentationVariant: [{ visualizations: [{ type: #AS_CHART${pvQ} }] }]`;
+    lines.splice(annotateIdx, 0, chartLine, pvLine);
+    return lines.join('\n');
+}
+/**
+ * Insert a `@Consumption.valueHelpDefinition` annotation ABOVE an EXISTING
+ * exposed element in a CDS view (DDLS) body — the same anchor rules as
+ * {@link promoteCdsFieldToLineItem}. This targets the VIEW source (a field
+ * annotation in a `define view`/DDLS body), NOT a metadata extension: a value
+ * help binding is a data-model annotation, so it lives on the view element.
+ *
+ * The anchor is the element's own declaration line, located by the declared
+ * element name (the alias after `as`, or the bare/`key`-prefixed name). The
+ * annotation is inserted immediately above that line at the same indentation,
+ * so it joins any existing contiguous annotation block.
+ *
+ * Fail-safe by design (mirrors promoteCdsFieldToLineItem):
+ *  - Refuses (throws) when the field cannot be uniquely identified (not found,
+ *    or ambiguous across multiple declarations).
+ *  - Refuses a multi-line / computed element (e.g. `case … end as Name`) whose
+ *    declaration line continues a larger expression — inserting above it would
+ *    split the expression.
+ *  - Idempotent: refuses when the field already carries a
+ *    `@Consumption.valueHelpDefinition` in the contiguous annotation block
+ *    directly above it.
+ *
+ * @param source full CDS view source
+ * @param opts.field   the EXISTING exposed element name to bind, e.g. `CustomerID`
+ * @param opts.entity  the value help provider CDS entity, e.g. `ZI_Customer`
+ * @param opts.element the provider element to bind to, e.g. `CustomerID`
+ * @param opts.additionalBinding optional extra binding { localElement, element }
+ * @returns the modified source
+ */
+export function insertCdsValueHelp(source, opts) {
+    const lines = source.split('\n');
+    // The element name a line declares, or null (same rule as promoteCdsFieldToLineItem).
+    const declaredName = (line) => {
+        const s = line.replace(/\s+$/, '').replace(/,$/, '').replace(/\s+$/, '');
+        const aliased = s.match(/\bas\s+(\w+)$/);
+        if (aliased)
+            return aliased[1];
+        const bare = s.trim().match(/^(?:key\s+)?(\w+)$/);
+        if (bare)
+            return bare[1];
+        return null;
+    };
+    // 1. Locate the unique element declaring `field`.
+    const defIdxs = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (declaredName(lines[i]) === opts.field)
+            defIdxs.push(i);
+    }
+    if (defIdxs.length === 0) {
+        throw new Error(`insertCdsValueHelp: field '${opts.field}' not found in the view element list`);
+    }
+    if (defIdxs.length > 1) {
+        throw new Error(`insertCdsValueHelp: field '${opts.field}' is ambiguous (${defIdxs.length} matches)`);
+    }
+    const defIdx = defIdxs[0];
+    // 2. Refuse a continuation line of a multi-line element (would split the expression).
+    const prev = defIdx > 0 ? lines[defIdx - 1].trim() : '';
+    const isFreshStart = prev === '' || prev === '{' || prev.startsWith('@') || prev.endsWith(',');
+    if (!isFreshStart) {
+        throw new Error(`insertCdsValueHelp: '${opts.field}' resolves to a multi-line/computed element; bind it manually or via /abap-refactor`);
+    }
+    // 3. Idempotency: refuse if `field` already has a valueHelpDefinition in the
+    //    contiguous single-line annotation block directly above defIdx.
+    for (let i = defIdx - 1; i >= 0 && lines[i].trim().startsWith('@'); i--) {
+        if (/@Consumption\.valueHelpDefinition\b/.test(lines[i])) {
+            throw new Error(`insertCdsValueHelp: '${opts.field}' already has a @Consumption.valueHelpDefinition`);
+        }
+    }
+    // 4. Build the annotation and insert it above defIdx at defIdx's indent.
+    const binding = opts.additionalBinding
+        ? `, additionalBinding: [{ localElement: '${opts.additionalBinding.localElement}', element: '${opts.additionalBinding.element}' }]`
+        : '';
+    const annotation = `@Consumption.valueHelpDefinition: [{ entity: { name: '${opts.entity}', element: '${opts.element}' }${binding} }]`;
+    const indent = (lines[defIdx].match(/^\s*/) ?? [''])[0];
+    lines.splice(defIdx, 0, `${indent}${annotation}`);
+    return lines.join('\n');
+}
+/**
+ * Insert a BDEF `side effects { … }` block into a MANAGED behavior entity body,
+ * immediately before the body's closing brace, at the body indentation — the
+ * SAME managed-BDEF `matchingClose` anchor machinery {@link insertBdefClause}
+ * and {@link insertBdefField} use. Managed-only policy is enforced HERE (the
+ * caller), not in the shared resolver (spec §9).
+ *
+ * NOTE: this is the RAP BDEF `side effects` clause (valid on ABAP Platform
+ * 2022+/S4H 2023), NOT a CDS `@Sideeffects` annotation (which is invalid on
+ * modern RAP). Emits:
+ *   side effects
+ *   {
+ *     field <sourceFields ', '> affects field <targetFields ', '>;
+ *   }
+ *
+ * Fail-safe by design:
+ *  - Refuses (throws) an UNMANAGED implementation — mirrors bdef-field/bdef-stub.
+ *  - When several behaviors exist and no alias is given, throws (via the shared
+ *    resolver) rather than guessing; throws too if a requested alias is absent.
+ *  - Refuses empty sourceFields or targetFields (an empty clause is invalid).
+ *
+ * @param source full managed BDEF source
+ * @param opts.entityAlias  the entity alias to extend; optional only when exactly
+ *                          one behavior is defined
+ * @param opts.sourceFields the trigger fields (`field <…>`) — non-empty
+ * @param opts.targetFields the affected fields (`affects field <…>`) — non-empty
+ * @returns the modified source
+ */
+export function insertBdefSideEffects(source, opts) {
+    if (!Array.isArray(opts.sourceFields) || opts.sourceFields.length === 0) {
+        throw new Error('insertBdefSideEffects: at least one source field is required');
+    }
+    if (!Array.isArray(opts.targetFields) || opts.targetFields.length === 0) {
+        throw new Error('insertBdefSideEffects: at least one target field is required');
+    }
+    const lines = source.split('\n');
+    const { bodyOpen, bodyClose, implKeyword } = resolveBehaviorEntityBody(lines, opts.entityAlias);
+    if (implKeyword === 'unmanaged') {
+        throw new Error('insertBdefSideEffects: unmanaged BDEF not supported (managed only)');
+    }
+    const clause = `field ${opts.sourceFields.join(', ')} affects field ${opts.targetFields.join(', ')};`;
+    // RAP permits exactly ONE `side effects { … }` block per entity. If the entity
+    // already has one inside its body, MERGE the new clause into it (never emit a
+    // second block — two blocks fail activation). Locate a `side effects` line
+    // within the resolved body, then its block braces via matchingClose.
+    let seLineIdx = -1;
+    for (let i = bodyOpen + 1; i < bodyClose; i++) {
+        if (/^\s*side\s+effects\b/.test(lines[i])) {
+            seLineIdx = i;
+            break;
+        }
+    }
+    if (seLineIdx !== -1) {
+        let seOpen = -1;
+        for (let i = seLineIdx; i < bodyClose; i++) {
+            if (lines[i].includes('{')) {
+                seOpen = i;
+                break;
+            }
+        }
+        const seClose = seOpen === -1 ? -1 : matchingClose(lines, seOpen);
+        if (seOpen === -1 || seClose === -1) {
+            throw new Error('insertBdefSideEffects: found a "side effects" clause with no matching block braces');
+        }
+        // Idempotency: refuse an identical `field … affects field …;` already declared.
+        for (let i = seOpen + 1; i < seClose; i++) {
+            if (lines[i].trim() === clause) {
+                throw new Error(`insertBdefSideEffects: side effect '${clause.replace(/;$/, '')}' already declared`);
+            }
+        }
+        // Inner indent from an existing block entry; else block-open indent + 2 spaces.
+        let entryIndent = null;
+        for (let i = seOpen + 1; i < seClose; i++) {
+            if (lines[i].trim() !== '') {
+                entryIndent = (lines[i].match(/^\s*/) ?? [''])[0];
+                break;
+            }
+        }
+        if (entryIndent === null) {
+            entryIndent = ((lines[seOpen].match(/^\s*/) ?? [''])[0]) + '  ';
+        }
+        lines.splice(seClose, 0, `${entryIndent}${clause}`);
+        return lines.join('\n');
+    }
+    // No existing block: emit the full `side effects { … }` block at the body close.
+    const indent = bodyIndent(lines, bodyOpen, bodyClose);
+    lines.splice(bodyClose, 0, `${indent}side effects`, `${indent}{`, `${indent}  ${clause}`, `${indent}}`);
+    return lines.join('\n');
+}
+/**
+ * Build a single BDEF clause line for a validation, determination, or action
+ * stub. Text only — no insertion. Fail-safe refusals: empty operations,
+ * static `$self` result (a static action has no instance), static + instance
+ * features. See spec §4.1.
+ */
+export function buildClauseLine(kind, opts) {
+    if (kind === 'validation') {
+        const ops = (opts.ops ?? 'create; update;').trim();
+        if (ops === '')
+            throw new Error('buildClauseLine: empty operations set for validation');
+        return `validation ${opts.name} on save { ${ops} }`;
+    }
+    if (kind === 'determination') {
+        const trigger = opts.trigger ?? 'modify';
+        const ops = (opts.ops ?? 'create;').trim();
+        if (ops === '')
+            throw new Error('buildClauseLine: empty operations set for determination');
+        return `determination ${opts.name} on ${trigger} { ${ops} }`;
+    }
+    // action
+    if (opts.static && opts.features) {
+        throw new Error('buildClauseLine: a static action cannot have features: instance control (no instance exists)');
+    }
+    const parts = [];
+    if (opts.static)
+        parts.push('static');
+    parts.push('action');
+    if (opts.features)
+        parts.push('( features : instance )');
+    parts.push(opts.name);
+    if (opts.parameter)
+        parts.push(`parameter ${opts.parameter}`);
+    if (opts.result) {
+        const resultType = opts.resultType ?? '$self';
+        if (opts.static && resultType === '$self') {
+            throw new Error('buildClauseLine: a static action cannot return $self (no instance); give a typed resultType');
+        }
+        parts.push(`result ${opts.resultCard ?? '[1]'} ${resultType}`);
+    }
+    return `${parts.join(' ')};`;
+}