@ishlabs/cli 0.20.0 → 0.22.0

package/dist/lib/study-results-filters.js

@@ -0,0 +1,559 @@
+/**
+ * Pure filter pipeline for `ish study results`.
+ *
+ * Input  : the raw `GET /studies/{id}` payload, the raw
+ *          `GET /studies/{id}/participants` payload, the raw
+ *          `GET /studies/{id}/frames` payload (or [] when --frame wasn't
+ *          passed), and a `ResultsFilters` struct from the command surface.
+ * Output : a `FilteredResults` struct — the trimmed participant graph,
+ *          pre-filter counts on `totals_unfiltered`, and a `warnings[]`
+ *          list of modality-mismatch notes for the surface to surface on
+ *          stderr.
+ *
+ * Has no IO and no console side-effects — the caller (study results action)
+ * owns network calls and stderr; we just compute. That keeps the function
+ * trivially unit-testable and lets the projection builders (T3) consume the
+ * same shape without re-walking the graph.
+ *
+ * Defensive null handling is the load-bearing piece. See the plan's
+ * "Defensive handling of nullable fields" section — read it before editing
+ * any predicate.
+ */
+import { resolveId } from "./alias-store.js";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function asRecord(v) {
+    return v && typeof v === "object" && !Array.isArray(v)
+        ? v
+        : null;
+}
+function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+function asString(v) {
+    return typeof v === "string" && v.length > 0 ? v : null;
+}
+function normaliseFrames(rawFrames) {
+    const out = [];
+    for (const row of rawFrames) {
+        const r = asRecord(row);
+        if (!r)
+            continue;
+        const id = asString(r.id);
+        if (!id)
+            continue;
+        const versions = [];
+        for (const v of asArray(r.versions)) {
+            const vr = asRecord(v);
+            const vid = vr ? asString(vr.id) : null;
+            if (vid)
+                versions.push({ id: vid });
+        }
+        out.push({ id, name: asString(r.name), versions });
+    }
+    return out;
+}
+function normaliseAssignments(rawAssignments) {
+    const out = [];
+    for (const row of rawAssignments) {
+        const r = asRecord(row);
+        if (!r)
+            continue;
+        const id = asString(r.id);
+        if (!id)
+            continue;
+        const side = r.side === "a" || r.side === "b" ? r.side : null;
+        out.push({ id, name: asString(r.name), side });
+    }
+    return out;
+}
+function normaliseIterations(rawIterations) {
+    const out = [];
+    for (const row of rawIterations) {
+        const r = asRecord(row);
+        if (!r)
+            continue;
+        const id = asString(r.id);
+        if (!id)
+            continue;
+        out.push({ id, label: asString(r.label) });
+    }
+    return out;
+}
+/** Throw a ValidationError-tagged Error (the wrapper maps it to exit 2).
+ *  Optional `availableValues` rides along as a structured field in the
+ *  emitted JSON envelope so agents can parse the recovery set without
+ *  string-extracting it from the message (Pattern V from round 3). */
+function validationError(message, availableValues) {
+    const err = new Error(message);
+    err.name = "ValidationError";
+    if (availableValues && availableValues.length > 0) {
+        err.available_values = availableValues;
+    }
+    return err;
+}
+/** Resolve `--frame <ref>` into a set of frame_version_ids.
+ *
+ * Branches on shape:
+ *   - `f-<hex>`     → frame alias, resolves to a Frame UUID via alias-store
+ *   - full UUID     → first try Frame.id; if no match, treat as frame_version_id
+ *   - anything else → case-insensitive substring against `frame.name`
+ *
+ * Ambiguous substring matches (>1 frame) throw with the candidate list.
+ * No matches at all throw a not-found ValidationError listing alternatives.
+ */
+function resolveFrameRef(ref, frames) {
+    const matched = new Set();
+    const lookup = new Map();
+    const indexFrame = (frame) => {
+        for (const v of frame.versions) {
+            matched.add(v.id);
+            lookup.set(v.id, { frame_id: frame.id, frame_label: frame.name });
+        }
+    };
+    // Build a frame_version_id → frame lookup once; reused on the
+    // "is this a frame_version_id?" path.
+    const fvToFrame = new Map();
+    for (const f of frames) {
+        for (const v of f.versions)
+            fvToFrame.set(v.id, f);
+    }
+    // 1. Frame alias (f-…) — resolve to a Frame UUID via alias-store.
+    if (/^f-[0-9a-f]{3,}$/i.test(ref)) {
+        const resolved = resolveId(ref); // throws not_found if alias is unknown
+        const frame = frames.find((f) => f.id === resolved);
+        if (!frame) {
+            throw validationError(`Frame alias "${ref}" resolved to ${resolved}, but no frame with that id exists on this study.`);
+        }
+        indexFrame(frame);
+        return { matchedFrameVersionIds: matched, frameVersionLookup: lookup };
+    }
+    // 2. Full UUID — try Frame.id first, then frame_version_id.
+    if (UUID_RE.test(ref)) {
+        const frame = frames.find((f) => f.id === ref);
+        if (frame) {
+            indexFrame(frame);
+            return { matchedFrameVersionIds: matched, frameVersionLookup: lookup };
+        }
+        const parentByVersion = fvToFrame.get(ref);
+        if (parentByVersion) {
+            // Treat as frame_version_id — match only this single version.
+            matched.add(ref);
+            lookup.set(ref, { frame_id: parentByVersion.id, frame_label: parentByVersion.name });
+            return { matchedFrameVersionIds: matched, frameVersionLookup: lookup };
+        }
+        throw validationError(`No frame or frame_version matches "${ref}" on this study. ` +
+            `Run \`ish study results <id> --get frames\` (or check the frames endpoint) to see the list.`);
+    }
+    // 3. Case-insensitive substring against frame.name. The plan calls
+    //    for the ambiguous-match error to list candidates explicitly.
+    const needle = ref.toLowerCase();
+    const candidates = frames.filter((f) => f.name && f.name.toLowerCase().includes(needle));
+    if (candidates.length === 0) {
+        // Pattern V: dedupe + cap the frame list so duplicates (workspace-side
+        // data hazards) don't double-list in the error prose. Carry the
+        // deduped list as a structured `available_values` field for agents.
+        const dedupedNames = Array.from(new Set(frames
+            .map((f) => f.name)
+            .filter((n) => typeof n === "string"))).slice(0, 10);
+        const hint = dedupedNames.length > 0
+            ? ` Available frames: ${dedupedNames.join(", ")}.`
+            : " This study has no named frames yet.";
+        throw validationError(`--frame "${ref}" matched no frames on this study.${hint}`, dedupedNames);
+    }
+    if (candidates.length > 1) {
+        const names = Array.from(new Set(candidates.map((c) => c.name).filter((n) => !!n)));
+        throw validationError(`--frame "${ref}" is ambiguous — matched ${candidates.length} frames: ${names.join(", ")}. ` +
+            `Use a more specific substring, a full Frame UUID, or an \`f-…\` alias.`, names);
+    }
+    indexFrame(candidates[0]);
+    return { matchedFrameVersionIds: matched, frameVersionLookup: lookup };
+}
+/** Resolve `--assignment <ref>` into a set of assignment_ids.
+ *
+ * UUID → exact match. Otherwise case-insensitive substring against name.
+ * Unlike --frame, multiple matches are NOT ambiguous — the user might
+ * legitimately want every "Sign up *" assignment; we just OR them.
+ */
+function resolveAssignmentRef(ref, assignments) {
+    const out = new Set();
+    if (UUID_RE.test(ref)) {
+        const m = assignments.find((a) => a.id === ref);
+        if (!m) {
+            throw validationError(`No assignment matches "${ref}" on this study.`);
+        }
+        out.add(m.id);
+        return out;
+    }
+    const needle = ref.toLowerCase();
+    for (const a of assignments) {
+        if (a.name && a.name.toLowerCase().includes(needle))
+            out.add(a.id);
+    }
+    if (out.size === 0) {
+        const names = assignments
+            .map((a) => a.name)
+            .filter((n) => !!n)
+            .slice(0, 10);
+        const hint = names.length > 0 ? ` Available: ${names.join(", ")}.` : "";
+        throw validationError(`--assignment "${ref}" matched no assignments on this study.${hint}`);
+    }
+    return out;
+}
+/** Resolve `--iteration <ref>` to a single iteration_id, or null if no
+ *  match (caller errors). Accepts UUID, iteration alias (`i-…`), or label. */
+function resolveIterationRef(ref, iterations) {
+    // Pattern M: iteration aliases (`i-…`) are the canonical short ID
+    // everywhere else in the CLI; accept them here too. Try alias resolution
+    // first, then fall through to UUID-direct, then label match.
+    let candidate = ref;
+    if (ref.startsWith("i-")) {
+        try {
+            candidate = resolveId(ref);
+        }
+        catch {
+            // Unknown alias — let the downstream "matched no iterations" branch
+            // emit the labels hint; the resolveId error doesn't add value here.
+        }
+    }
+    if (UUID_RE.test(candidate)) {
+        const m = iterations.find((i) => i.id === candidate);
+        if (!m) {
+            throw validationError(`No iteration matches "${ref}" on this study.`);
+        }
+        return m.id;
+    }
+    // Labels are uppercase A-Z by backend constraint; do a case-insensitive
+    // exact compare so `--iteration a` works as well as `--iteration A`.
+    const upper = ref.toUpperCase();
+    const m = iterations.find((i) => (i.label ?? "").toUpperCase() === upper);
+    if (!m) {
+        const labels = iterations
+            .map((i) => i.label)
+            .filter((n) => !!n);
+        const hint = labels.length > 0 ? ` Available labels: ${labels.join(", ")}.` : "";
+        throw validationError(`--iteration "${ref}" matched no iterations on this study.${hint}`);
+    }
+    return m.id;
+}
+/** Resolve --participant to a UUID (alias or full UUID, via resolveId). */
+function resolveParticipantRef(ref) {
+    // resolveId throws not_found for unknown aliases / invalid IDs.
+    return resolveId(ref);
+}
+/** Get the modality of the study. Returns a normalised lowercase string
+ *  ("interactive" | "chat" | "video" | "audio" | "text" | "image" |
+ *   "document"), or "unknown" if missing. */
+function getModality(study) {
+    const m = asString(study.modality);
+    return m ? m.toLowerCase() : "unknown";
+}
+/** True if the study is participant_pair chat (where --side is meaningful). */
+function isParticipantPair(study) {
+    if (getModality(study) !== "chat")
+        return false;
+    // mode_details lives under either `mode_details` on the study or
+    // `iteration.details.mode_details` per-iteration. The study-level
+    // `pair_mode` field (if present) is the cheap check; otherwise we
+    // peek at the assignments — pair studies have side="a"/"b" set.
+    const assignments = asArray(study.assignments);
+    for (const raw of assignments) {
+        const a = asRecord(raw);
+        if (a && (a.side === "a" || a.side === "b"))
+            return true;
+    }
+    return false;
+}
+/** Return true if the interaction's parent assignment has the given side. */
+function interactionMatchesSide(interaction, assignmentSideById, wantedSide) {
+    const aid = asString(interaction.assignment_id);
+    if (!aid)
+        return false;
+    const side = assignmentSideById.get(aid);
+    return side === wantedSide;
+}
+/** Read `actions[0].data` defensively. Returns {} when actions is empty
+ *  or the first row has no data block. */
+function firstActionData(interaction) {
+    const actions = asArray(interaction.actions);
+    if (actions.length === 0)
+        return {};
+    const first = asRecord(actions[0]);
+    if (!first)
+        return {};
+    const data = asRecord(first.data);
+    return data ?? {};
+}
+/** Predicate: --segment <ref> matches this interaction.
+ *
+ *  Numeric ref → equality against `data.segment_index`.
+ *  Non-numeric → case-insensitive substring against `data.segment_label`.
+ */
+function interactionMatchesSegment(interaction, segmentRef) {
+    const data = firstActionData(interaction);
+    const asInt = Number(segmentRef);
+    if (Number.isInteger(asInt) && segmentRef.trim() !== "") {
+        return data.segment_index === asInt;
+    }
+    const label = asString(data.segment_label);
+    if (!label)
+        return false;
+    return label.toLowerCase().includes(segmentRef.toLowerCase());
+}
+/** Predicate: --turn <n> matches this interaction. */
+function interactionMatchesTurn(interaction, turn) {
+    const data = firstActionData(interaction);
+    return data.turn_index === turn;
+}
+/** Per-participant step filter. Walks `participant_assignments[].step_results[]`,
+ *  keeps verdict rows whose step_id OR step.name match the user's ref, and
+ *  optionally returns the evidence_interaction_ids set so the caller can
+ *  drop interactions outside the evidence (when --include-evidence is set).
+ *
+ *  Returns null when this participant has no surviving step_results — the
+ *  caller treats that as "no match" for the participant.
+ */
+function filterStepsOnParticipant(participant, stepRef) {
+    const assignments = asArray(participant.participant_assignments);
+    const needle = stepRef.toLowerCase();
+    const filteredAssignments = [];
+    const evidence = new Set();
+    let kept = 0;
+    for (const raw of assignments) {
+        const a = asRecord(raw);
+        if (!a)
+            continue;
+        const steps = asArray(a.step_results);
+        const survivors = [];
+        for (const sraw of steps) {
+            const s = asRecord(sraw);
+            if (!s)
+                continue;
+            const sid = asString(s.step_id);
+            const sname = asString(s.name);
+            const matchesId = sid !== null && sid.toLowerCase() === needle;
+            const matchesName = sname !== null && sname.toLowerCase().includes(needle);
+            if (!matchesId && !matchesName)
+                continue;
+            survivors.push(s);
+            for (const eid of asArray(s.evidence_interaction_ids)) {
+                const eidStr = asString(eid);
+                if (eidStr)
+                    evidence.add(eidStr);
+            }
+            kept += 1;
+        }
+        if (survivors.length > 0) {
+            filteredAssignments.push({ ...a, step_results: survivors });
+        }
+        else {
+            // Preserve the assignment row but drop step_results entirely so
+            // downstream consumers see "this participant ran this assignment
+            // but no matching step verdicts" cleanly.
+            filteredAssignments.push({ ...a, step_results: [] });
+        }
+    }
+    if (kept === 0)
+        return null;
+    return { filteredAssignments, evidenceInteractionIds: evidence };
+}
+/**
+ * Pure entry point. See file-level comment for input/output contract.
+ */
+export function applyResultsFilters(study, participants, rawFrames, filters) {
+    const warnings = [];
+    const modality = getModality(study);
+    const frames = normaliseFrames(rawFrames);
+    const assignments = normaliseAssignments(asArray(study.assignments));
+    const iterations = normaliseIterations(asArray(study.iterations));
+    const assignmentSideById = new Map(assignments.map((a) => [a.id, a.side]));
+    // --- Resolve refs upfront so we can fail fast with clear errors. ---
+    let matchedFrameVersionIds = new Set();
+    let frameVersionLookup = new Map();
+    if (filters.frame !== undefined) {
+        if (modality !== "interactive") {
+            warnings.push(`--frame is only meaningful on interactive studies; ignored on modality "${modality}".`);
+        }
+        else {
+            const resolved = resolveFrameRef(filters.frame, frames);
+            matchedFrameVersionIds = resolved.matchedFrameVersionIds;
+            frameVersionLookup = resolved.frameVersionLookup;
+        }
+    }
+    let matchedAssignmentIds = null;
+    if (filters.assignment !== undefined) {
+        matchedAssignmentIds = resolveAssignmentRef(filters.assignment, assignments);
+    }
+    let matchedIterationId = null;
+    if (filters.iteration !== undefined) {
+        matchedIterationId = resolveIterationRef(filters.iteration, iterations);
+    }
+    let matchedParticipantId = null;
+    if (filters.participant !== undefined) {
+        matchedParticipantId = resolveParticipantRef(filters.participant);
+    }
+    // --- Modality-mismatch warnings (filter still runs but degrades to no-op). ---
+    if (filters.segment !== undefined) {
+        if (modality === "interactive" ||
+            modality === "chat" ||
+            modality === "image" ||
+            modality === "unknown") {
+            warnings.push(`--segment is only meaningful on video, audio, text, or document studies; ignored on modality "${modality}".`);
+        }
+    }
+    if (filters.turn !== undefined && modality !== "chat") {
+        warnings.push(`--turn is only meaningful on chat studies; ignored on modality "${modality}".`);
+    }
+    if (filters.side !== undefined && !isParticipantPair(study)) {
+        warnings.push(`--side is only meaningful on participant_pair chat studies; ignored on modality "${modality}".`);
+    }
+    // Normalise sentiment labels to lowercase up-front (case-insensitive).
+    const sentimentFilter = filters.sentiment
+        ? new Set(filters.sentiment.map((s) => s.toLowerCase()))
+        : null;
+    const actorFilter = filters.actor ? filters.actor.toLowerCase() : null;
+    // Set of warnings that downgrade a flag to a no-op for the predicate walk.
+    const segmentActive = filters.segment !== undefined && modality !== "interactive"
+        && modality !== "chat" && modality !== "image" && modality !== "unknown";
+    const turnActive = filters.turn !== undefined && modality === "chat";
+    const sideActive = filters.side !== undefined && isParticipantPair(study);
+    const frameActive = filters.frame !== undefined && modality === "interactive";
+    // Track whether ANY interaction-level filter is on. Determines whether
+    // we drop empty participants or keep them (per plan §3 "empty participants").
+    const interactionLevelFilterActive = frameActive ||
+        segmentActive ||
+        turnActive ||
+        sideActive ||
+        matchedAssignmentIds !== null ||
+        sentimentFilter !== null ||
+        actorFilter !== null;
+    // --- Pre-filter totals (for the totals_unfiltered envelope field). ---
+    let unfilteredInteractionCount = 0;
+    for (const p of participants) {
+        unfilteredInteractionCount += asArray(p.interactions).length;
+    }
+    const totals_unfiltered = {
+        participant_count: participants.length,
+        interaction_count: unfilteredInteractionCount,
+    };
+    // --- Walk participants. ---
+    const out = [];
+    for (const participant of participants) {
+        // 1. Participant-level filters (drop the whole row up-front).
+        if (matchedParticipantId !== null &&
+            asString(participant.id) !== matchedParticipantId) {
+            continue;
+        }
+        if (matchedIterationId !== null &&
+            asString(participant.iteration_id) !== matchedIterationId) {
+            continue;
+        }
+        // 2. --step is per-participant: rewrites participant_assignments
+        //    and surfaces evidence_interaction_ids if --include-evidence.
+        let evidenceInteractionIds = null;
+        let rewrittenAssignments = null;
+        if (filters.step !== undefined) {
+            const stepResult = filterStepsOnParticipant(participant, filters.step);
+            if (!stepResult) {
+                // This participant has no matching step verdicts — drop entirely
+                // (--step is participant-level "matched at least one verdict").
+                continue;
+            }
+            rewrittenAssignments = stepResult.filteredAssignments;
+            if (filters.includeEvidence) {
+                evidenceInteractionIds = stepResult.evidenceInteractionIds;
+            }
+        }
+        // 3. Walk interactions[] and drop those failing any predicate.
+        const survivingInteractions = [];
+        for (const raw of asArray(participant.interactions)) {
+            const interaction = asRecord(raw);
+            if (!interaction)
+                continue;
+            // --frame (interactive only)
+            if (frameActive) {
+                const fvId = asString(interaction.frame_version_id);
+                if (fvId === null) {
+                    if (!filters.includeUnmatched)
+                        continue;
+                    // Keep this row; the projection layer surfaces it under the
+                    // synthetic `_unmatched` bucket. We don't mutate the row here;
+                    // the lookup map simply lacks an entry, which the projection
+                    // layer interprets as "_unmatched".
+                }
+                else if (!matchedFrameVersionIds.has(fvId)) {
+                    continue;
+                }
+            }
+            // --segment (video/audio/text/document)
+            if (segmentActive) {
+                if (!interactionMatchesSegment(interaction, filters.segment)) {
+                    continue;
+                }
+            }
+            // --turn (chat)
+            if (turnActive) {
+                if (!interactionMatchesTurn(interaction, filters.turn)) {
+                    continue;
+                }
+            }
+            // --side (participant_pair chat)
+            if (sideActive) {
+                if (!interactionMatchesSide(interaction, assignmentSideById, filters.side)) {
+                    continue;
+                }
+            }
+            // --assignment
+            if (matchedAssignmentIds !== null) {
+                const aid = asString(interaction.assignment_id);
+                if (!aid || !matchedAssignmentIds.has(aid))
+                    continue;
+            }
+            // --actor
+            if (actorFilter !== null) {
+                const actor = asString(interaction.actor);
+                if (!actor || actor.toLowerCase() !== actorFilter)
+                    continue;
+            }
+            // --sentiment (drops null-sentiment rows only when this filter set)
+            if (sentimentFilter !== null) {
+                const sentiment = asRecord(interaction.sentiment);
+                const label = sentiment ? asString(sentiment.label) : null;
+                if (!label || !sentimentFilter.has(label.toLowerCase()))
+                    continue;
+            }
+            // --include-evidence (paired with --step)
+            if (evidenceInteractionIds !== null) {
+                const iid = asString(interaction.id);
+                if (!iid || !evidenceInteractionIds.has(iid))
+                    continue;
+            }
+            survivingInteractions.push(interaction);
+        }
+        // 4. Drop participants with zero surviving interactions only when
+        //    an interaction-level filter is set (preserves the stable schema
+        //    when the caller just asked "who ran?" without slicing).
+        if (interactionLevelFilterActive && survivingInteractions.length === 0) {
+            continue;
+        }
+        const next = {
+            ...participant,
+            interactions: survivingInteractions,
+        };
+        if (rewrittenAssignments !== null) {
+            next.participant_assignments = rewrittenAssignments;
+        }
+        out.push(next);
+    }
+    // The frames list returned to the caller is the raw payload (only the
+    // surface uses it for the `--get frames` shortcut). The projection
+    // layer relies on `frameVersionLookup` instead.
+    return {
+        study: { ...study },
+        participants: out,
+        frames: rawFrames,
+        totals_unfiltered,
+        warnings,
+        matchedFrameVersionIds,
+        frameVersionLookup,
+    };
+}