create-ailk 0.24.0 → 0.25.1

package/templates/apps/api/src/services/answer-distributions.ts

@@ -1,138 +0,0 @@
-/**
- * @file answer-distributions.ts
- * @description Shared per-question answer bucketing (#4771 D4).
- *
- * Extracted from `waitlist-dashboard.ts`'s `computeMetricRow` (the original
- * inline `distributions` body) — moved verbatim, not rewritten, so
- * `waitlist-dashboard.test.ts` stays green with NO edits to that file (the
- * AC 7 regression floor).
- *
- * Takes already-flattened answer maps, not rows: `waitlist-dashboard.ts`
- * passes `leads.map((l) => l.payload)`; `flow-aggregate.ts` passes
- * `sessions.map((s) => flattenSessionState(s.state))`. That is what lets one
- * implementation serve two different row types without either service
- * knowing about the other's.
- *
- * Hosted as a THIRD, neutral module rather than inside `flow-aggregate.ts`
- * (the issue's own `## Scope` names only that file) — a deliberate scope
- * extension per `rules/worker-contract.md` § Mid-task scope expansion:
- * hosting the shared helper in `flow-aggregate.ts` would make the operator
- * dashboard import from the flow-aggregate service, an import direction no
- * reader would predict from the names.
- */
-
-import { logger } from "@working-theory/observability";
-import type { WaitlistAnswerType } from "@working-theory/validation";
-
-/**
- * Defensive upper bound on an aggregation read (Medium finding, PR #4687
- * security review). Caps the raw row count any SINGLE scoped read can
- * return, so a `kind:"all"` aggregation spanning many sites (or a flow with
- * many completed sessions) cannot load an unbounded result set into memory.
- * Generous enough that no real deployment should hit it yet measured — if
- * one does, the affected read undercounts rather than growing unbounded,
- * and `logAggregationCapHit` below leaves a signal to act on (measure, then
- * follow up with a real bound or DB-side aggregation).
- */
-export const MAX_AGGREGATION_ROWS = 20_000;
-
-export function logAggregationCapHit(where: string, rowCount: number): void {
-  if (rowCount < MAX_AGGREGATION_ROWS) return;
-  logger.warn(
-    { where, rowCount, cap: MAX_AGGREGATION_ROWS },
-    "[answer-distributions] aggregation read hit its row cap — results may undercount",
-  );
-}
-
-/** A question's declared option set + the two fields the bucketer needs. */
-export type AnswerDistributionQuestion = {
-  id: string;
-  answerType: WaitlistAnswerType;
-  // `| undefined` (not just `?`) — the repo's `exactOptionalPropertyTypes`
-  // distinguishes "key absent" from "key present with value undefined", and
-  // both `WaitlistQuestion.options` and `WaitlistExperimentConfig`'s own
-  // `.optional()`-inferred fields are of the latter, wider shape.
-  options?: readonly { value: string }[] | undefined;
-};
-
-export type AnswerDistributionOption = {
-  value: string;
-  count: number;
-  share: number;
-};
-
-export type AnswerDistribution = {
-  questionId: string;
-  answerType: WaitlistAnswerType;
-  answered: number;
-  options: AnswerDistributionOption[];
-};
-
-/**
- * Read one question's answer out of an already-flattened answer map — moved
- * verbatim from `waitlist-dashboard.ts`'s (formerly local) `readPayloadAnswer`.
- */
-export function readPayloadAnswer(
-  payload: unknown,
-  questionId: string,
-): string | string[] | undefined {
-  if (typeof payload !== "object" || payload === null) return undefined;
-  const value = (payload as Record<string, unknown>)[questionId];
-  if (typeof value === "string" && value.length > 0) return value;
-  if (Array.isArray(value)) {
-    const strings = value.filter((v): v is string => typeof v === "string");
-    return strings.length > 0 ? strings : undefined;
-  }
-  return undefined;
-}
-
-/**
- * Bucket every declared question's answers across a set of already-flattened
- * answer maps — moved verbatim from `computeMetricRow`'s inline
- * `distributions` body. A value outside a question's declared options is
- * counted under `"(other)"`; `text` / `email` / `url` questions are never
- * charted (empty `options`, `answered` still populated).
- */
-export function computeAnswerDistributions(
-  questions: readonly AnswerDistributionQuestion[],
-  answerSets: readonly unknown[],
-): AnswerDistribution[] {
-  return questions.map((q) => {
-    const answeredSets = answerSets.filter(
-      (payload) => readPayloadAnswer(payload, q.id) !== undefined,
-    );
-    const answered = answeredSets.length;
-    if (
-      q.answerType === "text" ||
-      q.answerType === "email" ||
-      q.answerType === "url"
-    ) {
-      return {
-        questionId: q.id,
-        answerType: q.answerType,
-        answered,
-        options: [],
-      };
-    }
-    const declared = new Set((q.options ?? []).map((o) => o.value));
-    const counts = new Map<string, number>();
-    for (const payload of answeredSets) {
-      const value = readPayloadAnswer(payload, q.id);
-      const values = Array.isArray(value)
-        ? value
-        : value !== undefined
-          ? [value]
-          : [];
-      for (const v of values) {
-        const bucket = declared.has(v) ? v : "(other)";
-        counts.set(bucket, (counts.get(bucket) ?? 0) + 1);
-      }
-    }
-    const options = [...counts.entries()].map(([value, count]) => ({
-      value,
-      count,
-      share: answered > 0 ? count / answered : 0,
-    }));
-    return { questionId: q.id, answerType: q.answerType, answered, options };
-  });
-}