@teamscala/service-boot 0.23.481 → 0.23.492

package/src/fn-routers/assessment-report-data.ts

@@ -1,485 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten @indivisible-unit owner=lane/idle-pools-hold-the-ceiling reason="one report-shaping unit: band selection, narrative and chart shaping change together"
- * @edit edit directly
- *
- * report-data.ts — quiz-results → report data generation.
- *
- * Shapes a stored assessment response into the data the report puck_page
-
- * renders. The response already carries total_score + category_scores
- * (computed at submit time), so this is pure shaping — no re-scoring and no
- * authored copy. The `computeReportData` resolver_fn (a resource_loader
- * source, key `reportData`) runs this at SSR; the report blocks bind its
- * fields through the unified page-data surface (`dataSource:"page-data"` +
- * `fieldPath:"reportData.<key>"`).
- *
- * @see scala-docs/curated/apps/messaging.md is unrelated; the stage model
- * lives on `assessments.stage_bands` (migration 560/561).
- */
-
-import type { ReportResearchInput, ResearchReportData } from "./assessment-research-report-data.ts";
-import {
-	buildResearchReportData,
-	mergeNextSteps,
-	readResearchFindings,
-} from "./assessment-research-report-data.ts";
-
-/** A chart data point — structural match for @teamscala/chart-block's ChartPoint. */
-export interface ReportChartPoint {
-	label: string;
-	value: number;
-	color?: string;
-}
-
-/** A derived pillar position for the Positioning card (label + advisory summary). */
-export interface PillarPosition {
-	label: string;
-	summary: string;
-}
-
-/** One roadmap phase — a focus word plus its actions. */
-export interface RoadmapPhase {
-	focus: string;
-	actions: string[];
-}
-
-/**
- * A list item carrying its own ordinal. The number lives WITH the item so a
- * fixed-slot layout cannot print a badge for an item that does not exist: a
- * stage authoring four strengths into six slots leaves slots five and six with
- * no number and no text, rather than a bare numeral beside empty space. Numbers
- * spelled in the page instead would be a second copy of the list's length.
- */
-export interface NumberedItem {
-	index: string;
-	text: string;
-}
-
-/** A titled action with its explanatory line. */
-export interface TitledAction {
-	title: string;
-	description: string;
-}
-
-/**
- * One stage band, as authored on `assessments.stage_bands`. Every field is
- * copy the business owns; nothing here is computed. `max` is the inclusive
- * upper bound of the band — the final band omits it and catches the rest.
- */
-export interface StageBand {
-	name: string;
-	max?: number;
-	tagline?: string;
-	executiveSummary?: string;
-	strongestAreas?: string[];
-	priorityActions?: TitledAction[];
-	strategicFocus?: string;
-	strengths?: string[];
-	opportunities?: string[];
-	twelveMonthTarget?: string;
-	/**
-	 * The remaining elements of Anna's five-page template. Every one is COPY,
-	 * authored per stage like the rest — none can be derived from the response.
-	 * Wiring them here makes each a row edit rather than a build task: the page
-	 * binds them and hides the section (`visibleWhenPath`) until a stage fills
-	 * it in, so Anna can land them one at a time without a deploy.
-	 */
-	whoYouHelp?: string;
-	knownFor?: string;
-	insights?: string[];
-	contentThemes?: TitledAction[];
-	contentRhythm?: string;
-	northStar?: string;
-	priorityFocus?: string;
-	priorityFocusSummary?: string;
-	recommendedTier?: string;
-	tierSummary?: string;
-	whyItFits?: string;
-	whatItSolves?: string;
-	implementationFocus?: string;
-	expectedOutcome?: string;
-	finalWord?: string;
-	roadmap?: Record<string, RoadmapPhase>;
-	pillarNotes?: Record<string, string>;
-}
-
-/**
- * One pillar as the report presents it: the authored label and subtitle, this
- * person's score, the stage's note, and the pillar's colour. Held in the
- * assessment's own category order (not sorted by score) because the design
- * shows the three pillars in a fixed sequence with fixed colours.
- */
-export interface PillarCard {
-	label: string;
-	subtitle: string;
-	value: number;
-	max: number;
-	note: string;
-	color: string;
-}
-
-/** Per-category display authored on `assessments.category_descriptions`. */
-export interface CategoryDisplay {
-	description?: string;
-	subtitle?: string;
-	color?: string;
-	max?: number;
-}
-
-/** The shape a report resource_loader stamps into loaderData for the blocks. */
-export interface ReportData {
-	/** the three pillars in authored order, for the pillar cards */
-	pillarCards: PillarCard[];
-	reportScore: ReportChartPoint[];
-	reportPillars: ReportChartPoint[];
-	narrative: string;
-	totalScore: number;
-	/** overall band label — the Snapshot stage badge */
-	stage: string;
-	/** band advice — the Snapshot stage summary */
-	stageSummary: string;
-	/** highest-scoring pillar — the Positioning "Strongest Pillar" column */
-	strongest: PillarPosition | null;
-	/** mid pillar — the Positioning "Biggest Opportunity" column */
-	opportunity: PillarPosition | null;
-	/** lowest pillar — the Positioning "Authority Gap" column */
-	authorityGap: PillarPosition | null;
-	/** section 4 — what this person already has going for them */
-	strongestAreas: string[];
-	/** section 6 — the numbered actions for this stage */
-	priorityActions: TitledAction[];
-	/** section 7 */
-	strategicFocus: string;
-	/** section 8, left column */
-	strengths: string[];
-	/** section 8, right column */
-	opportunities: string[];
-	/** section 8 left, numbered for badge rendering */
-	strengthsList: NumberedItem[];
-	/** section 8 right, numbered for badge rendering */
-	opportunitiesList: NumberedItem[];
-	/** section 9 */
-	twelveMonthTarget: string;
-	/** section 10 — three phases, each a focus word plus four actions */
-	roadmap: RoadmapPhase[];
-	/** the research half of the report — `{present:false}` when no research pass exists */
-	research: ResearchReportData;
-	/** Anna's remaining template elements — empty until a stage authors them. */
-	whoYouHelp: string;
-	knownFor: string;
-	insights: string[];
-	contentThemes: TitledAction[];
-	contentRhythm: string;
-	northStar: string;
-	priorityFocus: string;
-	priorityFocusSummary: string;
-	recommendedTier: string;
-	tierSummary: string;
-	whyItFits: string;
-	whatItSolves: string;
-	implementationFocus: string;
-	expectedOutcome: string;
-	finalWord: string;
-}
-
-/** Minimal view of the stored response — total_score + category_scores. */
-export interface ReportResponseInput {
-	total_score?: number | null;
-	category_scores?: Record<string, number> | null;
-}
-
-/**
- * The response fields the paired report needs beyond the score: the person's
- * names (prepared-for line) and the LinkedIn URL the research pairing
- * normalises.
- */
-export interface ReportPairResponseShape extends ReportResponseInput {
-	id?: string;
-	assessment_id?: string;
-	first_name?: string | null;
-	last_name?: string | null;
-	linkedin_url?: string | null;
-	website?: string | null;
-	completed_at?: Date | string | null;
-}
-
-/** Minimal view of the assessment metadata — title plus the stage model. */
-export interface ReportAssessmentInput {
-	title?: string | null;
-	stage_bands?: unknown;
-	/** authored pillar order, e.g. ["Be Seen", "Be Heard", "Be Chosen"] */
-	categories?: unknown;
-	/** per-pillar display: subtitle, colour, description */
-	category_descriptions?: unknown;
-}
-
-/** The fallback pillar colour when the assessment authors none. */
-const DEFAULT_PILLAR_COLOR = "var(--color-primary)";
-
-/**
- * Match a pillar label to its authored stage note.
- *
- * The stage designs key these notes by the distinctive word — `seen`, `heard`,
- * `chosen` — while the assessment names the pillars "Be Seen", "Be Heard",
- * "Be Chosen". A plain lowercase lookup therefore missed EVERY note, and the
- * positioning cards silently fell back to their generic role lines: present,
- * plausible, and identical for every respondent, so nothing looked broken.
-
- * Tries the whole label first, then the last word, so either authoring style
- * resolves and neither has to know about the other.
- */
-export function pillarNote(band: StageBand | null, label: string): string {
-	const notes = band?.pillarNotes;
-	if (!notes) return "";
-	const whole = label.trim().toLowerCase();
-	const lastWord = whole.split(/\s+/).pop() ?? whole;
-	return (notes[whole] ?? notes[lastWord] ?? "").trim();
-}
-
-/**
- * Build the pillar cards in the assessment's OWN category order. Sorting by
- * score is right for "strongest / gap" positioning and wrong here: a reader
- * comparing two reports needs the pillars in the same place every time, and
- * each pillar keeps one colour across every report.
- */
-export function buildPillarCards(
-	assessment: ReportAssessmentInput | null | undefined,
-	categoryScores: Record<string, number>,
-	band: StageBand | null,
-): PillarCard[] {
-	const categories = Array.isArray(assessment?.categories)
-		? (assessment.categories as unknown[]).filter(
-				(c): c is string => typeof c === "string" && c.length > 0,
-			)
-		: Object.keys(categoryScores);
-	const display = (
-		assessment?.category_descriptions && typeof assessment.category_descriptions === "object"
-			? assessment.category_descriptions
-			: {}
-	) as Record<string, CategoryDisplay | string>;
-	return categories.map((label) => {
-		const raw = display[label];
-		const cfg: CategoryDisplay = typeof raw === "string" ? { description: raw } : (raw ?? {});
-		const score = Number(categoryScores[label] ?? 0);
-		return {
-			label,
-			subtitle: cfg.subtitle ?? "",
-			value: Number.isFinite(score) ? Math.max(0, Math.round(score)) : 0,
-			max: typeof cfg.max === "number" && cfg.max > 0 ? cfg.max : 100,
-			note: pillarNote(band, label) || cfg.description || "",
-			color: cfg.color || DEFAULT_PILLAR_COLOR,
-		};
-	});
-}
-
-/**
- * Read the authored bands off the assessment row. Returns [] when the column
- * is null or malformed, which is the signal to fall back rather than throw —
- * a report that renders a score with no stage copy is degraded; one that 500s
- * because a JSON column is empty is broken.
- */
-export function readStageBands(assessment?: ReportAssessmentInput | null): StageBand[] {
-	const raw = assessment?.stage_bands;
-	if (!raw || typeof raw !== "object") return [];
-	const bands = (raw as { bands?: unknown }).bands;
-	if (!Array.isArray(bands)) return [];
-	return bands.filter(
-		(band): band is StageBand =>
-			!!band && typeof band === "object" && typeof (band as StageBand).name === "string",
-	);
-}
-
-/**
- * Select the band a score falls in. Bands are ascending by `max`; the first
- * whose `max` the score does not exceed wins, and a band without `max` is the
- * catch-all. Authored order is respected rather than re-sorted, so a
- * mis-ordered row is visible in the output instead of silently corrected.
- */
-export function selectStageBand(bands: StageBand[], score: number): StageBand | null {
-	for (const band of bands) {
-		if (typeof band.max !== "number") return band;
-		if (score <= band.max) return band;
-	}
-	return bands.length > 0 ? (bands[bands.length - 1] ?? null) : null;
-}
-
-/**
- * The narrative is authored per band and carries `{{score}}` where the design
- * spelled a number, so one band serves every score inside it. With no band,
- * the fallback states the score and nothing it cannot support.
- */
-export function generateNarrative(
-	totalScore: number,
-	band: StageBand | null,
-	assessment?: ReportAssessmentInput | null,
-): string {
-	const authored = band?.executiveSummary?.trim();
-	if (authored) return authored.replaceAll("{{score}}", String(totalScore));
-	const title = assessment?.title?.trim() || "your assessment";
-	return `You scored ${totalScore} on ${title}.`;
-}
-
-/** Pair each item with its 1-based ordinal for badge rendering. */
-export function numberItems(items: string[] | undefined): NumberedItem[] {
-	if (!Array.isArray(items)) return [];
-	return items
-		.filter((text): text is string => typeof text === "string" && text.trim().length > 0)
-		.map((text, i) => ({ index: String(i + 1), text: text.trim() }));
-}
-
-/** Flatten the authored `{month1, month2, month3}` map into render order. */
-export function orderRoadmap(roadmap: Record<string, RoadmapPhase> | undefined): RoadmapPhase[] {
-	if (!roadmap || typeof roadmap !== "object") return [];
-	return Object.keys(roadmap)
-		.sort((a, b) => a.localeCompare(b, "en", { numeric: true }))
-		.map((key) => roadmap[key])
-		.filter((phase): phase is RoadmapPhase => !!phase && Array.isArray(phase.actions));
-}
-
-/**
- * Resolver call shape: the resolver_fn executor invokes every resolver as
- * `fn({ input, client, params })` (see resolveByResolverFn in
- * @teamscala/service-boot/resolve-from-loader-config). computeReportData is
- * registered as the `computeReportData` resolver_fn row, so it receives that
- * context — input.response / input.research / input.assessment come from the
- * loader's resolver_input, already PAIRED by the resolveReportHalves resolver
- * (research attaches to a response by normalised LinkedIn identity — both
- * halves resolved, or the research half alone for a research-only person).
- */
-export function computeReportData({
-	input,
-}: {
-	input: {
-		response?: ReportPairResponseShape | null;
-		assessment?: ReportAssessmentInput | null;
-		research?: ReportResearchInput | null;
-		brandName?: string | null;
-	};
-}): ReportData {
-	const { response, assessment } = input;
-	const research = input.research ?? null;
-	const bands = readStageBands(assessment);
-	const researchData = buildResearchReportData({
-		research,
-		response,
-		assessment,
-		bands,
-		resolveBand: (score: number) => selectStageBand(bands, score),
-		brandName: input.brandName,
-	});
-	// Research-only reports (no quiz response) take their headline score from
-	// the research pass so the Snapshot and pillar sections render from the
-	// only scoring that exists; both halves present, the response stays the
-	// subject of section one and the research feeds sections two through five.
-	const scores = response ??
-		(research
-			? {
-					total_score: research.total_score,
-					category_scores: research.category_scores,
-				}
-			: null);
-	const totalScore = Math.max(0, Math.round(Number(scores?.total_score ?? 0)));
-	const categoryScores = scores?.category_scores ?? {};
-	const reportScore: ReportChartPoint[] = [{ label: "Score", value: totalScore }];
-	const reportPillars: ReportChartPoint[] = Object.entries(categoryScores)
-		.filter(([, value]) => Number.isFinite(Number(value)))
-		.map(([label, value]) => ({ label, value: Math.max(0, Math.round(Number(value))) }))
-		.filter((p) => p.label.length > 0)
-		.sort((a, b) => b.value - a.value);
-
-	const band = selectStageBand(bands, totalScore);
-	const findings = research ? readResearchFindings(research.findings) : {};
-	const nextSteps = research ? mergeNextSteps(band, findings) : null;
-	const narrative =
-		research && !response && researchData.execSummary
-			? researchData.execSummary
-			: generateNarrative(totalScore, band, assessment);
-	const pillarCards = buildPillarCards(assessment, categoryScores, band);
-	// The chart bars take each pillar's own colour, so the bar chart and the
-	// pillar cards cannot disagree about which colour means which pillar.
-	// Only an AUTHORED colour travels to the chart. When the assessment sets
-	// none, the bars keep the chart's own default rather than being stamped with
-	// the cards' fallback — an assessment that never asked for pillar colours
-	// gets exactly the output it got before.
-	const colorFor = new Map(
-		pillarCards.filter((c) => c.color !== DEFAULT_PILLAR_COLOR).map((c) => [c.label, c.color]),
-	);
-	for (const point of reportPillars) {
-		const color = colorFor.get(point.label);
-		if (color) point.color = color;
-	}
-
-	// The positioning trio names the pillar; the advisory line beside it is the
-	// band's note for that pillar when one is authored, otherwise the generic
-	// role of that column. Falling back per-column rather than dropping the
-	// whole card keeps the section rendering while copy is still being written.
-	const noteFor = (label: string, fallback: string): string =>
-		pillarNote(band, label) || fallback;
-	const pos = (p: ReportChartPoint | undefined, fallback: string): PillarPosition | null =>
-		p ? { label: p.label, summary: noteFor(p.label, fallback) } : null;
-
-	const strongest = pos(
-		reportPillars[0],
-		"Your strongest pillar — protect and compound this advantage.",
-	);
-	const opportunity =
-		reportPillars.length >= 3
-			? pos(
-					reportPillars[1],
-					"Your biggest growth opportunity — focused effort here lifts overall authority.",
-				)
-			: null;
-	const authorityGap =
-		reportPillars.length >= 2
-			? pos(
-					reportPillars[reportPillars.length - 1],
-					"Your lowest pillar — the single biggest lever for improvement right now.",
-				)
-			: null;
-
-	return {
-		pillarCards,
-		reportScore,
-		reportPillars,
-		narrative,
-		totalScore,
-		stage: band?.name ?? "",
-		stageSummary: band?.tagline ?? "",
-		strongest,
-		opportunity,
-		authorityGap,
-		// Section five: the research pass's person-specific content wins
-		// field-by-field; without research these are the band's copy, exactly
-		// as every report before this table rendered them.
-		strongestAreas: nextSteps?.strongestAreas ?? band?.strongestAreas ?? [],
-		priorityActions: nextSteps?.priorityActions ?? band?.priorityActions ?? [],
-		strategicFocus: nextSteps?.strategicFocus ?? band?.strategicFocus ?? "",
-		strengths: nextSteps?.strengths ?? band?.strengths ?? [],
-		opportunities: nextSteps?.opportunities ?? band?.opportunities ?? [],
-		strengthsList: numberItems(nextSteps?.strengths ?? band?.strengths),
-		opportunitiesList: numberItems(nextSteps?.opportunities ?? band?.opportunities),
-		twelveMonthTarget: nextSteps?.twelveMonthTarget ?? band?.twelveMonthTarget ?? "",
-		roadmap: nextSteps?.roadmap ?? orderRoadmap(band?.roadmap),
-		research: {
-			...researchData,
-			groups: researchData.groups,
-			weakestAreasList: numberItems(researchData.weakestAreas),
-		},
-		whoYouHelp: band?.whoYouHelp ?? "",
-		knownFor: band?.knownFor ?? "",
-		insights: band?.insights ?? [],
-		contentThemes: band?.contentThemes ?? [],
-		contentRhythm: band?.contentRhythm ?? "",
-		northStar: band?.northStar ?? "",
-		priorityFocus: band?.priorityFocus ?? "",
-		priorityFocusSummary: band?.priorityFocusSummary ?? "",
-		recommendedTier: band?.recommendedTier ?? "",
-		tierSummary: band?.tierSummary ?? "",
-		whyItFits: band?.whyItFits ?? "",
-		whatItSolves: band?.whatItSolves ?? "",
-		implementationFocus: band?.implementationFocus ?? "",
-		expectedOutcome: band?.expectedOutcome ?? "",
-		finalWord: band?.finalWord ?? "",
-	};
-}