@cspeach/cli 1.0.0 → 1.1.0

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

@@ -766,6 +766,610 @@ export function insertMdeActionButton(source, opts) {
     }
     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,