common-qa-mcp 0.2.0 → 0.4.0

package/dist/adapters/simplifyqa/mapper.js

@@ -0,0 +1,858 @@
+// ---------------------------------------------------------------------------
+// Shared JSON pluckers. SQA endpoints wrap responses inconsistently -- one
+// controller returns `{ status, data: [...] }`, another returns the bare
+// array, another wraps it under `content` or the entity plural. `pickArray`
+// and `str` walk a list of candidate keys and return the first hit, matching
+// the tolerance the Java BackendClient built up against real responses.
+// ---------------------------------------------------------------------------
+export function pickArray(n, ...keys) {
+    for (const k of keys) {
+        const v = n?.[k];
+        if (Array.isArray(v))
+            return v;
+    }
+    return Array.isArray(n) ? n : [];
+}
+/** Hang `totalCount` off a mapped array as a side-band prop — SQA search responses expose it
+ *  at the top level as `totalCount` (with `total`/`totalRecords` as tolerant fallbacks). Undefined
+ *  when the raw response omits it (callers show `rows.length` as the total in that case). */
+export function withTotal(rows, raw) {
+    const t = raw?.totalCount ?? raw?.total ?? raw?.totalRecords;
+    if (typeof t === 'number')
+        rows.totalCount = t;
+    return rows;
+}
+export function str(n, ...keys) {
+    if (n == null)
+        return undefined;
+    for (const k of keys) {
+        const v = n[k];
+        if (typeof v === 'string' && v.length)
+            return v;
+        if (typeof v === 'number')
+            return String(v);
+    }
+    return undefined;
+}
+/** Accept a numeric id ("523") or a business code ("TC_523" / "US-897") — SQA REST paths
+ *  parseInt the segment, so a raw business key yields NaN → 404. Strips to the numeric run. */
+export function numericId(id) {
+    if (!id)
+        return '';
+    const m = id.match(/(\d+)/);
+    return m ? m[1] : id;
+}
+/** Map raw `tcfn_version` rows → neutral `TcVersion[]`. Shared between TC (versions inlined on
+ *  the `/tm/testcase/getById` doc) and FN (versions come from `/tm/function/version/:id/:pid`).
+ *  `currentVersionId` stamps `isCurrent:true` on the matching entry — pass undefined if unknown. */
+export function toVersionEntries(rawVersions, currentVersionId) {
+    return (Array.isArray(rawVersions) ? rawVersions : [])
+        .map((v) => {
+        const vid = str(v, 'id', '_id');
+        if (!vid)
+            return null;
+        const name = str(v, 'name') ?? vid;
+        const entry = { id: vid, name };
+        if (typeof v?.updateVersion === 'number')
+            entry.updateVersion = v.updateVersion;
+        const rev = str(v, 'reviewApproveStatus');
+        if (rev)
+            entry.reviewApproveStatus = rev;
+        const ex = str(v, 'executionType');
+        if (ex)
+            entry.executionType = ex;
+        if (currentVersionId && vid === currentVersionId)
+            entry.isCurrent = true;
+        return entry;
+    })
+        .filter((v) => v !== null);
+}
+/** SQA priority is UPPERCASE on the wire; neutral is lowercase. Unknown → 'medium'. */
+export function mapPriority(p) {
+    const s = typeof p === 'string' ? p.toLowerCase() : '';
+    return s === 'critical' || s === 'high' || s === 'medium' || s === 'low'
+        ? s : 'medium';
+}
+// ---------------------------------------------------------------------------
+// Steps. SQA stores step docs in two shapes with mostly-overlapping fields:
+//   • the `/tm/testcase/steps` COLLECTION (source of truth today), and
+//   • the INLINE `steps.manualSteps` / `steps.automationSteps` array on the TC doc
+//     (legacy, drifts against the collection).
+// Both use the same field names, so ONE mapper covers both. See adapter.ts
+// getTestCase for the read strategy (collection wins; inline is a fallback).
+// ---------------------------------------------------------------------------
+export const STEP_BLOCK_END_TYPES = new Set([
+    'ELSE', 'ELSE_IF', 'IF_END', 'FOR_END', 'WHILE', 'WHILE_END', 'ITERATOR_END',
+    'LOOP_ITERATION_END', 'FUNCTION_END',
+]);
+export const STEP_LOOP_START_TYPES = new Set([
+    'FOR_START', 'WHILE_START', 'ITERATOR_START', 'LOOP_ITERATION_START', 'DO',
+]);
+// SQA raw `stepType` → neutral Step.stepType + Step.controlFlow.kind. Enumerated from the
+// backend's own union (tcfn.service.js:2176 stepTypeMapping + validators). Everything not in
+// SIMPLE / CF_KINDS falls through as a plain automation step.
+const SIMPLE_STEP_KINDS = {
+    NORMAL_STATEMENT: 'web',
+    API: 'api',
+    COMPARE: 'compare',
+};
+const CF_KINDS = new Set([
+    'IF', 'ELSE', 'ELSE_IF', 'IF_END',
+    'WHILE_START', 'WHILE', 'WHILE_END',
+    'DO', 'DO_WHILE',
+    'FOR_START', 'FOR_END', 'LOOP',
+    'ITERATOR_START', 'ITERATOR_END',
+    'LOOP_ITERATION_START', 'LOOP_ITERATION_END',
+]);
+const SWITCH_KINDS = new Set([
+    'SWITCH_TO_API', 'SWITCH_TO_DB', 'SWITCH_TO_WEB', 'SWITCH_TO_MAINFRAME',
+    'SWITCH_TO_DESKTOP', 'SWITCH_TO_SAP', 'SWITCH_TO_IOS', 'SWITCH_TO_ANDROID',
+]);
+/** Squash a step's `recordedParam: { <paramId>: value }` map into a single readable cell
+ *  ("packageName=us.zoom, activity=..."). Names would be nicer than ids, but the id→name
+ *  resolution requires the project parameter dictionary — deferred; the raw id is unambiguous
+ *  and keeps this pure. */
+function formatRecordedParam(rp) {
+    if (!rp || typeof rp !== 'object')
+        return undefined;
+    const entries = Object.entries(rp).filter(([, v]) => v != null && v !== '');
+    if (!entries.length)
+        return undefined;
+    return entries.map(([k, v]) => `${k}=${String(v)}`).join(', ');
+}
+export function fromSqaStep(s, fallbackSeq) {
+    const sid = str(s, 'id', '_id', 'stepId');
+    const description = s?.description ?? '';
+    const expectedResult = s?.expectedResult ?? undefined;
+    const actionType = str(s, 'actionId', 'actionType') ?? '';
+    const seq = typeof s?.seq === 'number' ? s.seq : fallbackSeq;
+    const rawStepType = String(s?.stepType ?? '').toUpperCase();
+    // Neutral stepType routing. Manual TCs have executionType:'MANUAL' at the STEP level — that's
+    // the only reliable signal for the neutral 'manual' bucket (validators show `executionType`
+    // is a per-step string). Otherwise SIMPLE_STEP_KINDS wins, then CF, then FUNCTION, then a
+    // safe automation fallback.
+    let stepType = 'web';
+    if (str(s, 'executionType')?.toUpperCase() === 'MANUAL')
+        stepType = 'manual';
+    else if (SIMPLE_STEP_KINDS[rawStepType])
+        stepType = SIMPLE_STEP_KINDS[rawStepType];
+    else if (rawStepType === 'FUNCTION')
+        stepType = 'function';
+    else if (rawStepType === 'FUNCTION_END')
+        stepType = 'function_end';
+    else if (CF_KINDS.has(rawStepType))
+        stepType = 'control_flow';
+    else if (SWITCH_KINDS.has(rawStepType))
+        stepType = 'switch';
+    // Object linkage: SQA stores it as either scalar `objectId` OR nested `object.id`.
+    // Preserving the FK is what lets tc_heal / object_update_locators find the shared object.
+    let objectId = str(s, 'objectId');
+    if (!objectId && s?.object && typeof s.object === 'object') {
+        objectId = str(s.object, 'id');
+    }
+    const objectName = s?.object && typeof s.object === 'object' ? str(s.object, 'name') : undefined;
+    const step = {
+        n: seq,
+        description,
+        actionType,
+        stepType,
+        ...(sid ? { sourceId: sid } : {}),
+        ...(expectedResult ? { expectedResult } : {}),
+    };
+    if (objectId && objectId.toLowerCase() !== 'null') {
+        step.objectRef = { id: objectId, ...(objectName ? { name: objectName } : {}) };
+    }
+    // Control-flow: keep the RAW SQA kind on controlFlow.kind so the renderer can label it exactly
+    // as the UI does. `conditions.ifstring` is the human-readable expression the SQA UI shows in the
+    // condition column — carry it into conditionText.
+    if (stepType === 'control_flow' || stepType === 'function_end') {
+        const conditionText = str(s?.conditions, 'ifstring');
+        step.controlFlow = {
+            kind: rawStepType === 'FUNCTION_END' ? 'FUNCTION_END' : rawStepType,
+            ...(conditionText ? { conditionText } : {}),
+            ...(typeof s?.loopDuration === 'number' ? { maxIterations: s.loopDuration } : {}),
+        };
+    }
+    // FUNCTION step — carry every field the ROUND-TRIP save + a human render need. Backend
+    // sends functionId as a number, fnVersionId as a string uuid; the neutral surface is string.
+    if (stepType === 'function') {
+        const fnId = str(s, 'functionId');
+        const fnVersion = str(s, 'fnVersionId');
+        const sharedProject = str(s, 'sharedFnProjectId');
+        const sharedName = str(s, 'sharedFnProjectName');
+        if (fnId) {
+            step.functionCall = {
+                testCaseId: fnId,
+                ...(fnVersion ? { versionId: fnVersion } : {}),
+                ...(sharedProject ? { sharedProjectId: sharedProject } : {}),
+                ...(sharedName ? { testCaseName: sharedName } : {}),
+            };
+        }
+    }
+    // Value column: prefer recordedParam summary (concrete values) → falls through to parameterIds
+    // which surface as `${name}` tokens in the description already.
+    const recordedSummary = formatRecordedParam(s?.recordedParam);
+    if (recordedSummary)
+        step.value = recordedSummary;
+    return step;
+}
+// ---------------------------------------------------------------------------
+// Test cases.
+// `toTestCase` is the projection off the RAW /tm/testcase/getById doc — it
+// reads inline steps as a fallback. `applyCollectionSteps` replaces those with
+// the steps-collection view when that fetch succeeds, matching what the SQA UI
+// + execution + save paths use today.
+// ---------------------------------------------------------------------------
+export function toTestCase(doc) {
+    const id = str(doc, 'id', '_id', 'testcaseId');
+    const execType = str(doc, 'executionType') ?? '';
+    const category = execType.toUpperCase() === 'MANUAL' ? 'manual' : 'automated';
+    const priority = mapPriority(doc?.priority);
+    const description = str(doc, 'description');
+    const preconditions = str(doc, 'prerequisite', 'preconditions');
+    // storyRef + folderOrModule come off SQA as raw ints (userstoryId / moduleId). Project into
+    // neutral strings so `tc_automate` (SQA branch) can pre-fill the recording guide.
+    const userstoryId = typeof doc?.userstoryId === 'number' && doc.userstoryId > 0
+        ? String(doc.userstoryId) : undefined;
+    const moduleId = typeof doc?.moduleId === 'number' && doc.moduleId > 0
+        ? String(doc.moduleId) : undefined;
+    // Inline steps as fallback: prefer manualSteps for manual TCs, else automationSteps.
+    const stepsNode = doc?.steps;
+    let rawSteps = [];
+    if (stepsNode && typeof stepsNode === 'object') {
+        if (Array.isArray(stepsNode?.manualSteps) && stepsNode.manualSteps.length)
+            rawSteps = stepsNode.manualSteps;
+        else if (Array.isArray(stepsNode?.automationSteps))
+            rawSteps = stepsNode.automationSteps;
+        else if (Array.isArray(stepsNode))
+            rawSteps = stepsNode;
+    }
+    const steps = rawSteps.map((s, i) => fromSqaStep(s, i + 1));
+    // Versions: `/tm/testcase/getById` hangs a `versions[]` array on the doc (tcfn.service.js:1489),
+    // one entry per non-deleted tcfn_version. Current-version resolution mirrors the FE:
+    // `versionId` / `selectedVersionId` on the doc wins, else the doc's `versionsDetails.id`.
+    const currentVersionId = str(doc, 'versionId', 'selectedVersionId') ??
+        (doc?.versionsDetails && typeof doc.versionsDetails === 'object'
+            ? str(doc.versionsDetails, 'id', '_id', 'versionId')
+            : undefined);
+    const versions = toVersionEntries(Array.isArray(doc?.versions) ? doc.versions : [], currentVersionId);
+    return {
+        ...(id ? { id } : {}),
+        title: str(doc, 'name', 'title') ?? '',
+        ...(description ? { description } : {}),
+        priority,
+        ...(str(doc, 'status') ? { status: str(doc, 'status') } : {}),
+        category,
+        ...(preconditions ? { preconditions } : {}),
+        ...(userstoryId ? { storyRef: userstoryId } : {}),
+        ...(moduleId ? { folderOrModule: moduleId } : {}),
+        steps,
+        ...(versions.length ? { versions } : {}),
+        ...(currentVersionId ? { currentVersionId } : {}),
+    };
+}
+/** Overwrite `tc.steps` with the mapped collection-endpoint rows when non-empty. */
+export function applyCollectionSteps(tc, rows) {
+    if (!Array.isArray(rows) || rows.length === 0)
+        return tc;
+    const mapped = rows.map((s, i) => fromSqaStep(s, i + 1));
+    return { ...tc, steps: mapped };
+}
+// ---------------------------------------------------------------------------
+// Functions (reusable). Same `tcfnObj` collection as TCs — type='FN' instead of 'TC'.
+// Payload shape overlaps with TCs (id/code/name/description/executionType/status), plus
+// `fnType` (WEB/API/ANDROID/IOS) in place of `tcType`.
+// ---------------------------------------------------------------------------
+export function toFunctionSummary(row) {
+    const id = str(row, 'id', '_id', 'functionId') ?? '';
+    const code = str(row, 'code');
+    const name = str(row, 'name', 'title') ?? '';
+    const description = str(row, 'description');
+    const fnType = str(row, 'fnType', 'tcType');
+    const executionType = str(row, 'executionType');
+    const status = str(row, 'reviewApproveStatus', 'status');
+    const stepCount = typeof row?.stepCount === 'number' ? row.stepCount : undefined;
+    return {
+        id,
+        ...(code ? { code } : {}),
+        name,
+        ...(description ? { description } : {}),
+        ...(fnType ? { fnType } : {}),
+        ...(executionType ? { executionType } : {}),
+        ...(status ? { status } : {}),
+        ...(stepCount !== undefined ? { stepCount } : {}),
+    };
+}
+/** Full function doc → neutral QaFunction. Steps are attached separately by the adapter (fetched
+ *  from /tm/function/steps, same collection endpoint TCs use — just type='FN'). */
+export function toFunction(row) {
+    const summary = toFunctionSummary(row);
+    return { ...summary, steps: [] };
+}
+export function toTcSummary(row) {
+    const id = str(row, 'id', '_id', 'testcaseId') ?? '';
+    const code = str(row, 'code');
+    const title = str(row, 'name', 'title') ?? '';
+    const priority = (str(row, 'priority') ?? 'medium').toLowerCase();
+    const status = str(row, 'status');
+    const stepCount = typeof row?.stepCount === 'number' ? row.stepCount : undefined;
+    const technologyType = str(row, 'tcType');
+    const executionType = str(row, 'executionType');
+    const obsolete = typeof row?.obsolete === 'boolean' ? row.obsolete : undefined;
+    return {
+        id,
+        ...(code ? { code } : {}),
+        title,
+        priority,
+        ...(status ? { status } : {}),
+        ...(stepCount !== undefined ? { stepCount } : {}),
+        ...(technologyType ? { technologyType } : {}),
+        ...(executionType ? { executionType } : {}),
+        ...(obsolete !== undefined ? { obsolete } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Suites.
+// ---------------------------------------------------------------------------
+export function toSuiteSummary(row) {
+    const id = str(row, 'id', '_id', 'suiteId') ?? '';
+    const name = str(row, 'name', 'suiteName') ?? '';
+    const memberCount = Array.isArray(row?.testCases) ? row.testCases.length : undefined;
+    const suiteType = str(row, 'suiteType');
+    return {
+        id,
+        name,
+        ...(memberCount !== undefined ? { memberCount } : {}),
+        ...(suiteType ? { suiteType } : {}),
+    };
+}
+export function toSuite(doc) {
+    const id = str(doc, 'id', '_id', 'suiteId');
+    const description = str(doc, 'description');
+    const rawMembers = Array.isArray(doc?.testCases) ? doc.testCases : [];
+    const members = rawMembers.map((tc, i) => ({
+        tcId: str(tc, 'testcaseId', 'id', '_id') ?? '',
+        order: typeof tc?.seq === 'number' ? tc.seq : i + 1,
+    }));
+    return {
+        ...(id ? { id } : {}),
+        name: str(doc, 'name', 'suiteName') ?? '',
+        ...(description ? { description } : {}),
+        members,
+    };
+}
+// ---------------------------------------------------------------------------
+// User stories (`pm/userstory`). Business key comes back as `code` on SQA
+// (US_123 / US-897), so `key` in the neutral shape is populated from `code`.
+// ---------------------------------------------------------------------------
+export function toStorySummary(row) {
+    const id = str(row, 'id', '_id', 'userstoryId') ?? '';
+    const key = str(row, 'code', 'key', 'userStoryCode');
+    const title = str(row, 'name', 'title', 'storyName') ?? '';
+    const status = str(row, 'status', 'state');
+    const priority = str(row, 'priority');
+    return {
+        id,
+        ...(key ? { key } : {}),
+        title,
+        ...(status ? { status } : {}),
+        ...(priority ? { priority } : {}),
+    };
+}
+export function toDefectSummary(row) {
+    const id = str(row, 'id', '_id') ?? '';
+    const code = str(row, 'code');
+    const title = str(row, 'name', 'title') ?? '';
+    const state = str(row, 'state', 'status');
+    const severity = str(row, 'severity');
+    const priority = str(row, 'priority');
+    // `ownerId` is an ARRAY on the defect row (a defect can have several assignees) — see
+    // defect-interface.ts `ownerId: number[]` — unlike the single-value `ownerId` on stories/testcases.
+    const assignedTo = Array.isArray(row?.ownerId)
+        ? row.ownerId.map((v) => String(v ?? '')).filter((v) => v.length > 0)
+        : undefined;
+    const tcIds = Array.isArray(row?.selectedTestCase)
+        ? row.selectedTestCase
+            .map((tc) => (typeof tc === 'object' ? str(tc, 'testcaseId') : String(tc ?? '')))
+            .filter((v) => !!v)
+        : undefined;
+    return {
+        id,
+        ...(code ? { code } : {}),
+        title,
+        ...(state ? { state } : {}),
+        ...(severity ? { severity } : {}),
+        ...(priority ? { priority } : {}),
+        ...(assignedTo?.length ? { assignedTo } : {}),
+        ...(tcIds?.length ? { tcIds } : {}),
+    };
+}
+/** Maps a `/pm/task/search` row (see `Itask` in sqa-ui) to the neutral shape. `ownerId` is an array
+ *  on the task row, same as on a defect. */
+export function toTaskSummary(row) {
+    const id = str(row, 'id', '_id') ?? '';
+    const code = str(row, 'code');
+    const title = str(row, 'name', 'title') ?? '';
+    const state = str(row, 'state', 'status');
+    const priority = str(row, 'priority');
+    const assignedTo = Array.isArray(row?.ownerId)
+        ? row.ownerId.map((v) => String(v ?? '')).filter((v) => v.length > 0)
+        : undefined;
+    const defectId = typeof row?.defectId === 'number' && row.defectId > 0 ? String(row.defectId) : undefined;
+    return {
+        id,
+        ...(code ? { code } : {}),
+        title,
+        ...(state ? { state } : {}),
+        ...(priority ? { priority } : {}),
+        ...(assignedTo?.length ? { assignedTo } : {}),
+        ...(defectId ? { defectId } : {}),
+    };
+}
+export function toStory(doc) {
+    const base = toStorySummary(doc);
+    const description = str(doc, 'description', 'storyDescription');
+    // Acceptance criteria may be an array (of strings or {description}) or a newline-joined string.
+    const rawAc = doc?.acceptanceCriteria ?? doc?.acceptance_criteria;
+    let ac;
+    if (Array.isArray(rawAc)) {
+        ac = rawAc.map((c) => typeof c === 'string' ? c : String(c?.description ?? ''))
+            .filter((s) => s.length > 0);
+    }
+    else if (typeof rawAc === 'string') {
+        ac = rawAc.split(/\r?\n/).map((s) => s.trim()).filter((s) => s.length > 0);
+    }
+    return {
+        ...base,
+        ...(description ? { description } : {}),
+        ...(ac && ac.length ? { acceptanceCriteria: ac } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Epics (`pm/epic`) and features (`pm/feature`). Business keys come back as
+// `code` (EP_XXX / FT_XXX); numeric doc id is `id` (with `_id` as fallback).
+// ---------------------------------------------------------------------------
+export function toEpicSummary(row) {
+    const id = str(row, 'id', '_id', 'epicId') ?? '';
+    const key = str(row, 'code', 'key');
+    const name = str(row, 'name', 'epicName') ?? '';
+    const state = str(row, 'state', 'status');
+    return {
+        id,
+        ...(key ? { key } : {}),
+        name,
+        ...(state ? { state } : {}),
+    };
+}
+export function toEpic(doc) {
+    const base = toEpicSummary(doc);
+    const description = str(doc, 'description');
+    const plannedStartDate = str(doc, 'plannedStartDate');
+    const plannedEndDate = str(doc, 'plannedEndDate');
+    const rawEffort = doc?.estimatedEffort;
+    const rawOwner = doc?.ownerId;
+    return {
+        ...base,
+        ...(description ? { description } : {}),
+        ...(typeof rawEffort === 'number' ? { estimatedEffort: rawEffort } : {}),
+        ...(typeof rawOwner === 'number' ? { ownerId: rawOwner } : {}),
+        ...(plannedStartDate ? { plannedStartDate } : {}),
+        ...(plannedEndDate ? { plannedEndDate } : {}),
+    };
+}
+export function toFeatureSummary(row) {
+    const id = str(row, 'id', '_id', 'featureId') ?? '';
+    const key = str(row, 'code', 'key');
+    const name = str(row, 'name', 'featureName') ?? '';
+    const state = str(row, 'state', 'status');
+    const priority = str(row, 'priority');
+    const epicId = str(row, 'epicId');
+    return {
+        id,
+        ...(key ? { key } : {}),
+        name,
+        ...(state ? { state } : {}),
+        ...(priority ? { priority } : {}),
+        ...(epicId ? { epicId } : {}),
+    };
+}
+export function toFeature(doc) {
+    const base = toFeatureSummary(doc);
+    const description = str(doc, 'description');
+    const plannedStartDate = str(doc, 'plannedStartDate');
+    const plannedEndDate = str(doc, 'plannedEndDate');
+    const rawEffort = doc?.estimatedEffort;
+    const rawOwner = doc?.ownerId;
+    return {
+        ...base,
+        ...(description ? { description } : {}),
+        ...(typeof rawEffort === 'number' ? { estimatedEffort: rawEffort } : {}),
+        ...(typeof rawOwner === 'number' ? { ownerId: rawOwner } : {}),
+        ...(plannedStartDate ? { plannedStartDate } : {}),
+        ...(plannedEndDate ? { plannedEndDate } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Modules, releases, sprints.
+// ---------------------------------------------------------------------------
+export function toModuleSummary(row) {
+    const id = str(row, 'id', 'moduleId', '_id') ?? '';
+    const name = str(row, 'name', 'moduleName') ?? '';
+    const parentId = str(row, 'parentId', 'parent', 'parentModuleId');
+    return {
+        id,
+        name,
+        ...(parentId && parentId !== '0' ? { parentId } : {}),
+    };
+}
+export function toReleaseSummary(row) {
+    const id = str(row, 'id', '_id', 'releaseId') ?? '';
+    const name = str(row, 'name', 'releaseName') ?? '';
+    const state = str(row, 'state', 'status');
+    const plannedStartDate = str(row, 'plannedStartDate');
+    const plannedEndDate = str(row, 'plannedEndDate');
+    return {
+        id,
+        name,
+        ...(state ? { state } : {}),
+        ...(plannedStartDate ? { plannedStartDate } : {}),
+        ...(plannedEndDate ? { plannedEndDate } : {}),
+    };
+}
+export function toSprintSummary(row) {
+    const id = str(row, 'id', '_id', 'sprintId') ?? '';
+    const name = str(row, 'name', 'sprintName') ?? '';
+    const releaseId = str(row, 'releaseId');
+    const state = str(row, 'state', 'status');
+    const plannedStartDate = str(row, 'plannedStartDate');
+    const plannedEndDate = str(row, 'plannedEndDate');
+    return {
+        id,
+        name,
+        ...(releaseId ? { releaseId } : {}),
+        ...(state ? { state } : {}),
+        ...(plannedStartDate ? { plannedStartDate } : {}),
+        ...(plannedEndDate ? { plannedEndDate } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Objects — the shared object (locator) library. `attributes[]` is the SQA
+// wire shape; the neutral QaObject exposes it as `locators`.
+// ---------------------------------------------------------------------------
+export function toObject(doc) {
+    const id = str(doc, 'id', '_id');
+    const rawAttrs = Array.isArray(doc?.attributes) ? doc.attributes : [];
+    const locators = rawAttrs
+        .filter((a) => typeof a?.name === 'string' && typeof a?.value === 'string')
+        .map((a) => ({
+        name: String(a.name),
+        value: String(a.value),
+        ...(a.unique === true ? { unique: true } : {}),
+    }));
+    const name = str(doc, 'disname', 'description', 'placeholder') ?? '';
+    const objectType = str(doc, 'technology');
+    return {
+        ...(id ? { id } : {}),
+        name,
+        ...(objectType ? { objectType } : {}),
+        locators,
+    };
+}
+// ---------------------------------------------------------------------------
+// Write-side helpers. `${name}` token extraction + secret detection + payload
+// builders for POST/PUT /tm/testcase (`testcaseObj`).
+// ---------------------------------------------------------------------------
+const PARAM_TOKEN = /\$\{([A-Za-z0-9_]+)\}/g;
+/** Unique `${name}` tokens in a step description, in first-seen order. */
+export function extractParamNames(description) {
+    if (!description)
+        return [];
+    const seen = [];
+    for (const m of description.matchAll(PARAM_TOKEN)) {
+        const name = m[1];
+        if (!seen.includes(name))
+            seen.push(name);
+    }
+    return seen;
+}
+/** Auto-mask heuristic: names containing password/secret/token/apikey/auth/credential get
+ *  `protected:true` on parameter creation. A missed real secret is worse than a false positive
+ *  the user can uncheck in the UI. */
+export function looksSensitive(name) {
+    if (!name)
+        return false;
+    const n = name.toLowerCase();
+    return n.includes('password') || n.includes('passwd') || n.includes('secret')
+        || n.includes('token') || n.includes('apikey') || n.includes('api_key')
+        || n.includes('auth') || n.includes('credential');
+}
+/** Pick a default value for a param: `tc.data[name]` wins; else the step's own `value`; else "". */
+export function paramDefault(name, data, stepValue) {
+    if (data && Object.prototype.hasOwnProperty.call(data, name))
+        return String(data[name] ?? '');
+    return stepValue ?? '';
+}
+/** Neutral Step.stepType → SQA `technologyType` on the step + `tcType` on the TC.
+ *  Exported so the adapter's per-step resolver keys the action catalog by the same technology
+ *  labels the mapper writes into the step. */
+export const TECH_BY_STEPTYPE = {
+    web: 'WEB',
+    android: 'ANDROID',
+    api: 'API',
+    database: 'DATABASE',
+    mainframe: 'MAINFRAME',
+};
+/** Pick the tcType from the first step whose stepType we recognize as an automation technology.
+ *  Falls back to WEB — matches the SQA UI's default when the user starts a fresh automation TC. */
+export function deriveTcType(tc) {
+    for (const s of tc.steps ?? []) {
+        const tech = TECH_BY_STEPTYPE[s.stepType];
+        if (tech)
+            return tech;
+    }
+    return 'WEB';
+}
+/** SQA-empty `mailersList` shape — the frontend and joi validator expect the three arrays, not
+ *  a bare `{}`. Verified against the real create payload for TC-584. */
+const EMPTY_MAILERS = { users: [], nonUsers: [], groups: [] };
+/**
+ * Assemble the `testcaseObj` payload for POST/PUT /tm/testcase (multipart). Branches on
+ * `tc.category`: manual → `steps.manualSteps` (legacy behavior), automated → `steps.automationSteps`
+ * with resolved actionId/objectId/parameterIds. See `buildManualPayload` and
+ * `buildAutomationPayload` below for the per-branch shapes; both share the wrapper.
+ */
+export function buildTestcasePayload(inputs) {
+    return inputs.tc.category === 'automated'
+        ? buildAutomationPayload(inputs)
+        : buildManualPayload(inputs);
+}
+/**
+ * Manual TC payload. Mirrors Java's `buildTestcasePayload` exactly on wire shape:
+ *   - `tcfnObj` — TC-level meta. `deleted` is required on UPDATE and rejected on CREATE.
+ *   - `versionsDetails` — a minimal `{name:'v1.0', id:''}` stub matches what the SQA UI sends
+ *     for a fresh TC; UPDATE also carries `deleted:false` because the validator requires it.
+ *   - `steps.manualSteps` — one entry per neutral step; `automationSteps` is emitted empty.
+ *   - Every step gets `parameterIds[]` for the `${name}` tokens in its description.
+ */
+function buildManualPayload(inputs) {
+    const { projectId, moduleId, userstoryId, existingId, tc, paramIdByName } = inputs;
+    const tcfnObj = {
+        ...(existingId ? { id: Number.parseInt(existingId, 10) } : {}),
+        name: tc.title ?? '',
+        projectId,
+        moduleId,
+        ...(userstoryId != null ? { userstoryId } : {}),
+        obsolete: false,
+        ...(existingId ? { deleted: false } : {}),
+        tcType: 'WEB',
+        executionType: 'MANUAL',
+        customFields: {},
+        ...(tc.description ? { description: tc.description } : {}),
+        ...(tc.preconditions ? { prerequisite: tc.preconditions } : {}),
+    };
+    const versionsDetails = {
+        name: 'v1.0',
+        id: '',
+        ...(existingId ? { deleted: false } : {}),
+    };
+    const manualSteps = [];
+    const steps = Array.isArray(tc.steps) ? tc.steps : [];
+    steps.forEach((s, i) => {
+        const desc = s.description ?? '';
+        const step = {
+            projectId,
+            moduleId,
+            type: 'TC',
+            stepType: 'NORMAL_STATEMENT',
+            seq: i + 1,
+            description: desc,
+            expectedResult: s.expectedResult ?? '',
+            executionType: 'MANUAL',
+        };
+        const paramIds = [];
+        const recordedParam = {};
+        for (const name of extractParamNames(desc)) {
+            const id = paramIdByName.get(name);
+            if (id == null)
+                continue;
+            paramIds.push(id);
+            recordedParam[String(id)] = paramDefault(name, tc.data, undefined);
+        }
+        if (paramIds.length > 0) {
+            step['parameterIds'] = paramIds;
+            step['recordedParam'] = recordedParam;
+        }
+        manualSteps.push(step);
+    });
+    return {
+        tcfnObj,
+        versionsDetails,
+        steps: { automationSteps: [], manualSteps },
+        operation: 'TC',
+        type: 'TC',
+    };
+}
+/**
+ * Automation TC payload. Mirrors the shape observed on a saved SQA automation TC (TC-584, WEB +
+ * ANDROID validation samples):
+ *   - `tcfnObj.executionType: 'AUTOMATION'` + `originalExecutinType: 'AUTOMATION'`.
+ *   - `tcfnObj.tcType` derived from the first automation step's `stepType` (web / android / …).
+ *   - `tcfnObj.executionPlatform` — WEB defaults to Chrome server-side (omitted here), non-WEB
+ *     REQUIRES `tc.executionPlatform` from the caller (device serial + name).
+ *   - `steps.automationSteps[]` — one entry per neutral step. Each carries the resolved
+ *     `actionId` (numeric FK to the SQA `action` collection) + `objectId` (numeric FK to the
+ *     shared `object` collection, or null when the action doesn't need one) + `parameterIds` +
+ *     `recordedParam:{<id>:value}` (drives the default iteration on save).
+ *   - Always-present step defaults (`conditions`, `loop`, `stepLevelActions`, `attachments`)
+ *     are emitted every time — the joi validator + backend read these unconditionally on
+ *     execution, and the sample confirms they're present on simple straight-line steps too.
+ *
+ * Straight-line only in this cut — FUNCTION / IF / FOR / WHILE / API / SWITCH are ponytail-
+ * deferred to a follow-up (need a real control-flow sample to validate the `conditions.children[]`
+ * shape end-to-end).
+ */
+function buildAutomationPayload(inputs) {
+    const { projectId, moduleId, userstoryId, existingId, tc, paramIdByName, stepResolutions } = inputs;
+    const tcType = deriveTcType(tc);
+    // WEB: backend auto-defaults executionPlatform to Chrome (tcfn.service.js:206-213), so omit
+    // when the caller didn't supply one. Non-WEB: refuse the save early rather than land a broken
+    // TC — the backend doesn't default a real device for us.
+    if (tcType !== 'WEB' && !tc.executionPlatform) {
+        throw new Error(`Automation TC "${tc.title}" needs \`executionPlatform\` for tcType=${tcType} — set ` +
+            `tc.executionPlatform:{id:<deviceSerial>, name, technologyType:'${tcType}', type:'REAL_DEVICE'|'CLOUD_DEVICE'}. ` +
+            `For Android, call android_list_devices to see the available devices.`);
+    }
+    const tcfnObj = {
+        ...(existingId ? { id: Number.parseInt(existingId, 10) } : {}),
+        name: tc.title ?? '',
+        projectId,
+        moduleId,
+        ...(userstoryId != null ? { userstoryId } : {}),
+        obsolete: false,
+        ...(existingId ? { deleted: false } : {}),
+        tcType,
+        executionType: 'AUTOMATION',
+        originalExecutinType: 'AUTOMATION',
+        customFields: {},
+        mailersList: EMPTY_MAILERS,
+        suiteId: [],
+        defectId: [],
+        tags: [],
+        reviewApproveStatus: '',
+        ...(tc.executionPlatform ? { executionPlatform: tc.executionPlatform } : {}),
+        ...(tc.description ? { description: tc.description } : {}),
+        ...(tc.preconditions ? { prerequisite: tc.preconditions } : {}),
+    };
+    const versionsDetails = {
+        name: 'v1.0',
+        id: '',
+        syncONOFF: '',
+        executionType: 'AUTOMATION',
+        functionProjectIds: [projectId],
+        ...(existingId ? { deleted: false } : {}),
+    };
+    const automationSteps = [];
+    const steps = Array.isArray(tc.steps) ? tc.steps : [];
+    steps.forEach((s, i) => {
+        const desc = s.description ?? '';
+        const technologyType = TECH_BY_STEPTYPE[s.stepType] ?? tcType;
+        const resolution = stepResolutions?.[i];
+        if (!resolution) {
+            throw new Error(`Automation TC "${tc.title}" step ${i + 1}: missing action resolution — the adapter did ` +
+                'not resolve `actionId` for this step. Check that the neutral Step.actionType maps to a ' +
+                'known SQA action for this technology.');
+        }
+        // parameterIds: union of description ${tokens} + keys of step.recordedParam. `recordedParam`
+        // on the wire is keyed by NUMERIC paramId (JSON keys → strings), NOT by name.
+        const paramIds = [];
+        const recordedParamOut = {};
+        const seen = new Set();
+        const addParam = (name, value) => {
+            if (seen.has(name))
+                return;
+            seen.add(name);
+            const id = paramIdByName.get(name);
+            if (id == null)
+                return;
+            paramIds.push(id);
+            if (value !== undefined)
+                recordedParamOut[String(id)] = value;
+        };
+        for (const name of extractParamNames(desc))
+            addParam(name, tc.data?.[name] ?? s.value);
+        if (s.recordedParam) {
+            for (const [name, value] of Object.entries(s.recordedParam))
+                addParam(name, value);
+        }
+        const step = {
+            projectId,
+            moduleId,
+            type: 'TC',
+            stepType: 'NORMAL_STATEMENT',
+            seq: i + 1,
+            description: desc,
+            expectedResult: s.expectedResult ?? '',
+            executionType: 'AUTOMATION',
+            technologyType,
+            actionId: resolution.actionId,
+            objectId: resolution.objectId,
+            parameterIds: paramIds,
+            objectParameterIds: [],
+            recordedParam: recordedParamOut,
+            attachments: [],
+            conditions: { ifstring: '', children: [] },
+            loop: { loopType: 'for', loopIteration: null },
+            stepLevelActions: {
+                skip: s.flags?.skip ?? false,
+                captureScreenshot: s.flags?.screenshot ?? false,
+                continueOnFailure: s.flags?.continueOnFailure ?? false,
+                skippedReport: false,
+            },
+            ...(technologyType === 'WEB' ? { browserType: s.browserType ?? 'CHROME' } : {}),
+        };
+        automationSteps.push(step);
+    });
+    return {
+        tcfnObj,
+        versionsDetails,
+        steps: { automationSteps, manualSteps: [] },
+        operation: 'TC',
+        type: 'TC',
+    };
+}
+/** Neutral SavedRef from a POST/PUT /tm/testcase response. Tolerates a bare doc or a `data`-wrapped
+ *  response; prefers the business `code` (TC_xxx) for productUrl deep links but uses the numeric id
+ *  when only that is present. */
+export function toSavedRef(raw, created) {
+    const flat = (raw?.data ?? raw) ?? {};
+    const id = str(flat, 'id', '_id', 'testcaseId') ?? '';
+    return {
+        id,
+        created,
+    };
+}
+// ---------------------------------------------------------------------------
+// Suites (write). The update PUT reshapes the members list under a strict
+// allow-list; anything else on the raw doc is rejected. Shared helpers are:
+//   • normalizeSuiteEntry — copy an existing members[] row into the allow-list.
+//   • Adapter builds each ADD entry by fetching the target TC, so those helpers
+//     stay in the adapter (they need IO).
+// ---------------------------------------------------------------------------
+/** Copy an existing suite testCases[] row into the strict allow-list; drop `id`, audit fields, etc. */
+export function normalizeSuiteEntry(m) {
+    const out = {};
+    const keep = ['testcaseId', 'code', 'seq', 'stepId', 'version', 'versionId', 'tcType', 'projectId', 'executionPlatform'];
+    for (const k of keep)
+        if (m?.[k] !== undefined)
+            out[k] = m[k];
+    return out;
+}
+/** The 15+ allow-listed suite-level keys the update validator accepts. */
+export const SUITE_UPDATE_ALLOWED_KEYS = [
+    'id', 'name', 'description', 'state', 'suiteType', 'projectId', 'autoDefectLog',
+    'autoReExecCount', 'autoReExecTriggerOn', 'newBrowserSession', 'terminateOnFailure',
+    'minimumContainerCount', 'maximumContainerCount', 'copySuiteName', 'copiedFrom',
+    'mailersList', 'tags', 'customFields', 'agentId', 'cloudAgentId',
+    'lastSelectedExecutionType', 'updateVersion',
+];
+//# sourceMappingURL=mapper.js.map