@cspeach/cli 1.1.27 → 1.1.29

package/dist/tools/text-elements/pool.js

@@ -0,0 +1,250 @@
+/**
+ * Program text pool — pure logic for selection texts, text symbols and list
+ * headings. No SAP, no fs.
+ *
+ * ADT serves each part as a plain-text source (sap-client
+ * getTextElementsSource) and a PUT replaces the WHOLE part. So a write is
+ * always read → merge → write: the texts already there are kept byte for
+ * byte, only the named entries are added or changed. Never a blind replace.
+ *
+ * Source formats (S4H read-only capture 2026-10-04 + SAP_BASIS 754 captures):
+ *   selections  `P_MAXROW=Maximum Rows`, blank line between entries; SAP pads
+ *               the name to 8 chars on read (`S_BUDAT =Posting Date`). A
+ *               dictionary-referenced text carries a bare `@DDICReference`
+ *               line right above it. Some releases list screen fields with no
+ *               text as `NAME=?...` (754); S4H leaves them out.
+ *   symbols     `@MaxLength:N` then `001=Text`, blank line between entries.
+ *   headings    `listHeader=…`, blank line, `columnHeader_1..4=…` — always
+ *               all five lines.
+ */
+export const TEXT_ELEMENT_KINDS = ['selections', 'symbols', 'headings'];
+export const SELECTION_TEXT_MAX = 30;
+export const SYMBOL_TEXT_MAX = 132;
+export const LIST_HEADER_MAX = 70;
+export const COLUMN_HEADER_MAX = 132;
+/** SAP's marker for a selection-screen field that has no text yet. */
+export const UNTEXTED_MARKER = '?...';
+const HEADING_KEYS = ['listHeader', 'columnHeader_1', 'columnHeader_2', 'columnHeader_3', 'columnHeader_4'];
+export function isTextElementKind(k) {
+    return typeof k === 'string' && TEXT_ELEMENT_KINDS.includes(k);
+}
+/** Canonical key: selections/symbols upper-cased, headings in SAP's camelCase. */
+export function canonicalKey(kind, key) {
+    const k = key.trim();
+    if (kind !== 'headings')
+        return k.toUpperCase();
+    const hit = HEADING_KEYS.find((h) => h.toLowerCase() === k.toLowerCase());
+    return hit ?? k;
+}
+export function parseTextPool(kind, body) {
+    const out = [];
+    let pendingMax;
+    let pendingAnn = [];
+    for (const raw of body.split(/\r\n|\r|\n/)) {
+        if (raw.trim() === '')
+            continue;
+        if (raw.startsWith('@')) {
+            const m = /^@MaxLength:\s*(\d+)\s*$/i.exec(raw);
+            if (m && kind === 'symbols')
+                pendingMax = parseInt(m[1], 10);
+            else
+                pendingAnn.push(raw);
+            continue;
+        }
+        const eq = raw.indexOf('=');
+        if (eq < 0)
+            continue;
+        const key = canonicalKey(kind, raw.slice(0, eq));
+        const text = raw.slice(eq + 1);
+        const entry = { key, text };
+        if (kind === 'symbols' && pendingMax !== undefined)
+            entry.maxLength = pendingMax;
+        if (kind === 'selections' && text === UNTEXTED_MARKER) {
+            entry.text = '';
+            entry.untexted = true;
+        }
+        if (pendingAnn.length > 0)
+            entry.annotations = pendingAnn;
+        out.push(entry);
+        pendingMax = undefined;
+        pendingAnn = [];
+    }
+    return out;
+}
+export function formatTextPool(kind, entries) {
+    if (kind === 'headings') {
+        const byKey = new Map(entries.map((e) => [canonicalKey('headings', e.key), e.text]));
+        const v = (k) => byKey.get(k) ?? '';
+        return `listHeader=${v('listHeader')}\n\n`
+            + HEADING_KEYS.slice(1).map((k) => `${k}=${v(k)}\n`).join('');
+    }
+    if (kind === 'symbols') {
+        if (entries.length === 0)
+            return '';
+        return entries
+            .map((e) => {
+            const max = Math.min(Math.max(e.maxLength ?? 0, e.text.length, 1), SYMBOL_TEXT_MAX);
+            return [`@MaxLength:${max}`, ...(e.annotations ?? []), `${e.key}=${e.text}`].join('\n');
+        })
+            .join('\n\n') + '\n';
+    }
+    // selections — fields without a text are SAP's placeholder, not a text: never written back.
+    // Blank line between entries, `@DDICReference` right above its entry: the shape S4H serves.
+    const texted = entries.filter((e) => !e.untexted && e.text !== '');
+    if (texted.length === 0)
+        return '';
+    return texted
+        .map((e) => [...(e.annotations ?? []), `${e.key}=${e.text}`].join('\n'))
+        .join('\n\n') + '\n';
+}
+export function validateUpdates(kind, updates) {
+    const errs = [];
+    if (!Array.isArray(updates) || updates.length === 0)
+        return ['texts must name at least one entry'];
+    const seen = new Set();
+    for (const u of updates) {
+        if (typeof u?.key !== 'string' || typeof u?.text !== 'string') {
+            errs.push('every entry needs a key and a text (strings)');
+            continue;
+        }
+        const key = canonicalKey(kind, u.key);
+        const text = u.text;
+        if (seen.has(key))
+            errs.push(`${key}: named twice`);
+        seen.add(key);
+        if (/[\r\n]/.test(text))
+            errs.push(`${key}: a text must be one line`);
+        if (kind === 'selections') {
+            if (!/^[A-Z][A-Z0-9_]{0,7}$/.test(key))
+                errs.push(`${key}: not a selection-screen name (1-8 letters, digits, _)`);
+            if (text.trim() === '')
+                errs.push(`${key}: text is empty`);
+            if (text.length > SELECTION_TEXT_MAX)
+                errs.push(`${key}: selection text is ${text.length} chars — the limit is ${SELECTION_TEXT_MAX}`);
+        }
+        else if (kind === 'symbols') {
+            if (!/^[A-Z0-9]{3}$/.test(key))
+                errs.push(`${key}: a text symbol id is 3 letters/digits (TEXT-001 → 001)`);
+            if (text.trim() === '')
+                errs.push(`${key}: text is empty`);
+            if (text.length > SYMBOL_TEXT_MAX)
+                errs.push(`${key}: text symbol is ${text.length} chars — the limit is ${SYMBOL_TEXT_MAX}`);
+            if (u.max_length !== undefined) {
+                if (!Number.isInteger(u.max_length) || u.max_length < text.length || u.max_length > SYMBOL_TEXT_MAX) {
+                    errs.push(`${key}: max_length must be a whole number from the text length (${text.length}) to ${SYMBOL_TEXT_MAX}`);
+                }
+            }
+        }
+        else {
+            if (!HEADING_KEYS.includes(key))
+                errs.push(`${key}: headings are ${HEADING_KEYS.join(', ')}`);
+            const limit = key === 'listHeader' ? LIST_HEADER_MAX : COLUMN_HEADER_MAX;
+            if (text.length > limit)
+                errs.push(`${key}: heading is ${text.length} chars — the limit is ${limit}`);
+        }
+    }
+    return errs;
+}
+/** Merge updates into the existing entries. Validate first (validateUpdates). */
+export function mergeTextPool(kind, existing, updates) {
+    const entries = existing.map((e) => ({ ...e, ...(e.annotations ? { annotations: [...e.annotations] } : {}) }));
+    const index = new Map(entries.map((e, i) => [e.key, i]));
+    const r = { entries, added: [], changed: [], unchanged: [], kept: [], dictionaryReferenceDropped: [] };
+    const touched = new Set();
+    for (const u of updates) {
+        const key = canonicalKey(kind, u.key);
+        touched.add(key);
+        const at = index.get(key);
+        if (at === undefined) {
+            const e = { key, text: u.text };
+            if (kind === 'symbols')
+                e.maxLength = u.max_length ?? u.text.length;
+            entries.push(e);
+            index.set(key, entries.length - 1);
+            if (kind !== 'headings' || u.text !== '')
+                r.added.push(key);
+            continue;
+        }
+        const cur = entries[at];
+        const newMax = kind === 'symbols' ? (u.max_length ?? Math.max(cur.maxLength ?? 0, u.text.length)) : undefined;
+        const sameText = !cur.untexted && cur.text === u.text;
+        if (sameText && (kind !== 'symbols' || newMax === cur.maxLength)) {
+            r.unchanged.push(key);
+            continue;
+        }
+        if (cur.untexted || (kind === 'headings' && cur.text === ''))
+            r.added.push(key);
+        else
+            r.changed.push(key);
+        const next = { ...cur, text: u.text };
+        if (kind === 'selections')
+            next.untexted = false;
+        if (kind === 'symbols')
+            next.maxLength = newMax;
+        if (kind === 'selections' && cur.annotations?.some((a) => /^@DDIC/i.test(a))) {
+            next.annotations = cur.annotations.filter((a) => !/^@DDIC/i.test(a));
+            r.dictionaryReferenceDropped.push(key);
+        }
+        entries[at] = next;
+    }
+    for (const e of existing) {
+        if (touched.has(e.key))
+            continue;
+        if (e.untexted || e.text === '')
+            continue;
+        r.kept.push(e.key);
+    }
+    return r;
+}
+/**
+ * Selection-screen field names declared in a program source (PARAMETERS /
+ * SELECT-OPTIONS, chained or not). Comments are ignored. `hasIncludes` says
+ * the screen may also be declared in an include this scan cannot see.
+ */
+export function selectionScreenNames(source) {
+    const lines = source.split(/\r\n|\r|\n/).filter((l) => !l.startsWith('*')).map(stripLineComment);
+    const code = lines.join('\n');
+    const names = new Set();
+    const re = /(?:^|[\s.])(PARAMETERS|PARAMETER|SELECT-OPTIONS|SELECT-OPTION)\b\s*(:?)([^.]*)\./gim;
+    let m;
+    while ((m = re.exec(code)) !== null) {
+        const parts = m[2] === ':' ? m[3].split(',') : [m[3]];
+        for (const p of parts) {
+            const id = /^\s*([A-Za-z_][A-Za-z0-9_]*)/.exec(p);
+            if (id)
+                names.add(id[1].toUpperCase());
+        }
+    }
+    const hasIncludes = /^\s*INCLUDE\s+(?!STRUCTURE\b|TYPE\b)[A-Za-z0-9_/]+/im.test(code);
+    return { names, hasIncludes };
+}
+/** Drop a `"` comment, leaving quotes inside '…' and `…` literals alone. */
+function stripLineComment(line) {
+    let inQ = null;
+    for (let i = 0; i < line.length; i++) {
+        const c = line[i];
+        if (inQ) {
+            if (c === inQ)
+                inQ = null;
+        }
+        else if (c === "'" || c === '`' || c === '|') {
+            inQ = c;
+        }
+        else if (c === '"') {
+            return line.slice(0, i);
+        }
+    }
+    return line;
+}
+/**
+ * Snapshot-store key for one text-pool part: `PROG.TEXT_<KIND>`, name = the
+ * program. A dot keeps the store's type/name layout and can never collide
+ * with a real ABAP type code (same scheme as class includes, CLAS.<INCLUDE>).
+ */
+export function textElementsSnapshotType(kind) {
+    return `PROG.TEXT_${kind.toUpperCase()}`;
+}
+export function parseTextElementsSnapshotType(type) {
+    const m = /^PROG\.TEXT_(SELECTIONS|SYMBOLS|HEADINGS)$/i.exec(type);
+    return m ? m[1].toLowerCase() : null;
+}