@cspeach/cli 0.9.0 → 1.0.0

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

@@ -0,0 +1,810 @@
+/**
+ * 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');
+}
+/**
+ * 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(' ')};`;
+}