Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
14.5 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-or-later

import {createHash} from 'node:crypto';
import {CONTENT_I18N_MESSAGES} from '@app/api/content_i18n/ContentI18nMessages';
import type {ReportFlowDef} from '@app/api/report/flows/ReportFlowDefinitions';
import type {
	ReportFlowCopyKey,
	ReportFlowLinkId,
	ReportFlowNoticeDef,
	ReportFlowOptionDef,
	ReportFlowOutcomeDef,
	ReportFlowScreenDef,
} from '@app/api/report/flows/ReportFlowScreens';
import {getLegacyCategory, isReportReasonKey} from '@app/api/report/flows/ReportReasonCatalog';
import type {ReportFlowSurface, ReportFlowTargetType} from '@fluxer/schema/src/domains/report/ReportFlowSchemas';

export interface ReportFlowLibrary {
	flows: Record<ReportFlowTargetType, ReportFlowDef>;
	screens: ReadonlyArray<ReportFlowScreenDef>;
	notices: ReadonlyArray<ReportFlowNoticeDef>;
}

export interface ReportFlowInstance {
	selfHosted: boolean;
	guidelinesLinked: boolean;
}

type ReportFlowScreenKind = 'choice' | 'checklist' | 'info';

export interface ReportFlowVariantScreen {
	def: ReportFlowScreenDef;
	kind: ReportFlowScreenKind;
	subtitle: ReportFlowCopyKey | null;
	options: ReadonlyArray<ReportFlowOptionDef>;
}

export interface ReportFlowVariant {
	target: ReportFlowTargetType;
	surface: ReportFlowSurface;
	startScreenId: string;
	screens: ReadonlyMap<string, ReportFlowVariantScreen>;
	notices: ReadonlyArray<ReportFlowNoticeDef>;
	revisionHash: string;
}

const REPORT_FLOW_TARGETS: ReadonlyArray<ReportFlowTargetType> = ['message', 'user', 'guild'];
const REPORT_FLOW_SURFACES: ReadonlyArray<ReportFlowSurface> = ['in_app', 'dsa'];
const REPORT_FLOW_VARIANTS = REPORT_FLOW_TARGETS.flatMap((target) =>
	REPORT_FLOW_SURFACES.map((surface) => ({target, surface})),
);
const REPORT_FLOW_ID_PATTERN = /^[a-z0-9_]{1,48}$/;
const MAX_WALK_SCREENS = 10;
const REPORT_FLOW_CHECKED_INSTANCES: ReadonlyArray<ReportFlowInstance> = [
	{selfHosted: false, guidelinesLinked: true},
	{selfHosted: true, guidelinesLinked: false},
	{selfHosted: true, guidelinesLinked: true},
];

function getReportFlowScreenKind(screen: ReportFlowScreenDef): ReportFlowScreenKind {
	if (screen.checklist) {
		return 'checklist';
	}
	if (screen.nextScreenId !== undefined) {
		return 'info';
	}
	return 'choice';
}

function isLinkAvailable(link: ReportFlowLinkId, instance: ReportFlowInstance): boolean {
	switch (link) {
		case 'crisis_lines':
			return true;
		case 'guidelines':
			return instance.guidelinesLinked;
		case 'copyright':
			return !instance.selfHosted;
	}
}

function resolveScreenSubtitle(
	def: ReportFlowScreenDef,
	surface: ReportFlowSurface,
	instance: ReportFlowInstance,
): ReportFlowCopyKey | null {
	const variants = def.subtitleVariants;
	if (surface === 'dsa' && variants?.dsa !== undefined) {
		return variants.dsa;
	}
	if (instance.selfHosted && variants?.selfHosted !== undefined) {
		return variants.selfHosted;
	}
	return def.subtitle ?? null;
}

function isOptionInVariant(
	option: ReportFlowOptionDef,
	surface: ReportFlowSurface,
	instance: ReportFlowInstance,
): boolean {
	if (option.surface !== undefined && option.surface !== surface) {
		return false;
	}
	return option.outcome.type !== 'link' || isLinkAvailable(option.outcome.link, instance);
}

function getScreenEdges(screen: ReportFlowVariantScreen): Array<string> {
	const edges: Array<string> = [];
	for (const option of screen.options) {
		if (option.outcome.type === 'screen') {
			edges.push(option.outcome.screenId);
		}
	}
	if (screen.def.checklist?.outcome.type === 'screen') {
		edges.push(screen.def.checklist.outcome.screenId);
	}
	if (screen.def.nextScreenId !== undefined) {
		edges.push(screen.def.nextScreenId);
	}
	return edges;
}

function getScreenOutcomes(screen: ReportFlowVariantScreen): Array<ReportFlowOutcomeDef> {
	const outcomes = screen.options.map((option) => option.outcome);
	if (screen.def.checklist) {
		outcomes.push(screen.def.checklist.outcome);
	}
	return outcomes;
}

function canonicalOutcome(outcome: ReportFlowOutcomeDef): string {
	switch (outcome.type) {
		case 'screen':
			return `screen:${outcome.screenId}`;
		case 'submit':
			return `submit:${outcome.reason}`;
		case 'end':
			return outcome.noticeId === undefined ? 'end' : `end:${outcome.noticeId}`;
		case 'link':
			return `link:${outcome.link}`;
	}
}

function computeRevisionHash(
	target: ReportFlowTargetType,
	surface: ReportFlowSurface,
	startScreenId: string,
	screens: ReadonlyMap<string, ReportFlowVariantScreen>,
	notices: ReadonlyArray<ReportFlowNoticeDef>,
): string {
	const canonical = {
		target,
		surface,
		start: startScreenId,
		screens: [...screens.values()]
			.sort((a, b) => {
				if (a.def.id < b.def.id) {
					return -1;
				}
				if (a.def.id > b.def.id) {
					return 1;
				}
				return 0;
			})
			.map((screen) => ({
				id: screen.def.id,
				kind: screen.kind,
				title: screen.def.title,
				subtitle: screen.subtitle,
				urgent: screen.def.urgent === true,
				next: screen.def.nextScreenId ?? null,
				options: screen.options.map((option) => ({
					id: option.id,
					label: option.label,
					outcome: canonicalOutcome(option.outcome),
				})),
				checklist: screen.def.checklist
					? {
							items: screen.def.checklist.items.map((item) => ({
								id: item.id,
								label: item.label,
								description: item.description ?? null,
								reason: item.reason ?? null,
							})),
							min_checked: screen.def.checklist.minChecked,
							outcome: canonicalOutcome(screen.def.checklist.outcome),
						}
					: null,
			})),
		notices: notices.map((notice) => ({id: notice.id, title: notice.title, body: notice.body})),
	};
	return createHash('sha256').update(JSON.stringify(canonical)).digest('hex').slice(0, 16);
}

export function buildReportFlowVariant(
	library: ReportFlowLibrary,
	target: ReportFlowTargetType,
	surface: ReportFlowSurface,
	instance: ReportFlowInstance,
): ReportFlowVariant {
	const startScreenId = library.flows[target].start[surface];
	const screenDefs = new Map(library.screens.map((screen) => [screen.id, screen]));
	const screens = new Map<string, ReportFlowVariantScreen>();
	const noticeIds = new Set<string>();
	const queue = [startScreenId];
	for (let index = 0; index < queue.length; index++) {
		const screenId = queue[index];
		if (screens.has(screenId)) {
			continue;
		}
		const def = screenDefs.get(screenId);
		if (!def) {
			throw new Error(`Report flow ${target}/${surface} references an unknown screen: ${screenId}`);
		}
		const screen: ReportFlowVariantScreen = {
			def,
			kind: getReportFlowScreenKind(def),
			subtitle: resolveScreenSubtitle(def, surface, instance),
			options: (def.options ?? []).filter((option) => isOptionInVariant(option, surface, instance)),
		};
		screens.set(screenId, screen);
		for (const outcome of getScreenOutcomes(screen)) {
			if (outcome.type === 'end' && outcome.noticeId !== undefined) {
				noticeIds.add(outcome.noticeId);
			}
		}
		queue.push(...getScreenEdges(screen));
	}
	const notices = library.notices.filter((notice) => noticeIds.has(notice.id));
	return {
		target,
		surface,
		startScreenId,
		screens,
		notices,
		revisionHash: computeRevisionHash(target, surface, startScreenId, screens, notices),
	};
}

function collectDefinitionErrors(library: ReportFlowLibrary): Array<string> {
	const errors: Array<string> = [];
	const screenIds = new Set<string>();
	const noticeIds = new Set(library.notices.map((notice) => notice.id));
	const checkId = (id: string, where: string) => {
		if (!REPORT_FLOW_ID_PATTERN.test(id)) {
			errors.push(`${where}: id "${id}" does not match ${REPORT_FLOW_ID_PATTERN}`);
		}
	};
	const checkKey = (key: string | undefined, where: string) => {
		if (key !== undefined && !Object.hasOwn(CONTENT_I18N_MESSAGES, key)) {
			errors.push(`${where}: unknown copy key ${key}`);
		}
	};
	const checkOutcome = (outcome: ReportFlowOutcomeDef, where: string) => {
		if (outcome.type === 'submit' && !isReportReasonKey(outcome.reason)) {
			errors.push(`${where}: unknown reason ${outcome.reason}`);
		}
		if (outcome.type === 'end' && outcome.noticeId !== undefined && !noticeIds.has(outcome.noticeId)) {
			errors.push(`${where}: unknown notice ${outcome.noticeId}`);
		}
	};
	for (const notice of library.notices) {
		checkId(notice.id, `notice ${notice.id}`);
		checkKey(notice.title, `notice ${notice.id}`);
		checkKey(notice.body, `notice ${notice.id}`);
	}
	if (noticeIds.size !== library.notices.length) {
		errors.push('notice ids are not unique');
	}
	for (const screen of library.screens) {
		const where = `screen ${screen.id}`;
		checkId(screen.id, where);
		if (screenIds.has(screen.id)) {
			errors.push(`${where}: duplicate screen id`);
		}
		screenIds.add(screen.id);
		checkKey(screen.title, where);
		checkKey(screen.subtitle, where);
		checkKey(screen.subtitleVariants?.dsa ?? undefined, where);
		checkKey(screen.subtitleVariants?.selfHosted ?? undefined, where);
		const options = screen.options ?? [];
		const kind = getReportFlowScreenKind(screen);
		if (kind === 'checklist' && (options.length > 0 || screen.nextScreenId !== undefined)) {
			errors.push(`${where}: a checklist screen has no options and no next screen`);
		}
		if (kind === 'info' && options.some((option) => option.outcome.type !== 'link')) {
			errors.push(`${where}: an info screen only has link options`);
		}
		if (kind === 'choice' && !options.some((option) => option.outcome.type !== 'link')) {
			errors.push(`${where}: a choice screen needs at least one option that is not a link`);
		}
		const optionIds = new Set<string>();
		for (const option of options) {
			const optionWhere = `${where} option ${option.id}`;
			checkId(option.id, optionWhere);
			if (optionIds.has(option.id)) {
				errors.push(`${optionWhere}: duplicate option id`);
			}
			optionIds.add(option.id);
			checkKey(option.label, optionWhere);
			checkOutcome(option.outcome, optionWhere);
			const endsWithoutNotice = option.outcome.type === 'end' && option.outcome.noticeId === undefined;
			const linksToCopyright = option.outcome.type === 'link' && option.outcome.link === 'copyright';
			if ((endsWithoutNotice || linksToCopyright) && option.surface !== 'in_app') {
				errors.push(`${optionWhere}: a no-report or copyright link option must be limited to in_app`);
			}
		}
		if (!screen.checklist) {
			continue;
		}
		const {items, minChecked, outcome} = screen.checklist;
		const itemIds = new Set<string>();
		for (const item of items) {
			const itemWhere = `${where} item ${item.id}`;
			checkId(item.id, itemWhere);
			if (itemIds.has(item.id)) {
				errors.push(`${itemWhere}: duplicate item id`);
			}
			itemIds.add(item.id);
			checkKey(item.label, itemWhere);
			checkKey(item.description, itemWhere);
			if (item.reason !== undefined && !isReportReasonKey(item.reason)) {
				errors.push(`${itemWhere}: unknown reason ${item.reason}`);
			}
		}
		if (!Number.isInteger(minChecked) || minChecked < 1 || minChecked > items.length) {
			errors.push(`${where}: min checked must be between 1 and the item count`);
		}
		checkOutcome(outcome, `${where} checklist`);
	}
	for (const screen of library.screens) {
		const targets = [
			...(screen.options ?? []).flatMap((option) =>
				option.outcome.type === 'screen' ? [option.outcome.screenId] : [],
			),
			...(screen.checklist?.outcome.type === 'screen' ? [screen.checklist.outcome.screenId] : []),
			...(screen.nextScreenId !== undefined ? [screen.nextScreenId] : []),
		];
		for (const next of targets) {
			if (!screenIds.has(next)) {
				errors.push(`screen ${screen.id}: next screen ${next} is not defined`);
			}
		}
	}
	for (const {target, surface} of REPORT_FLOW_VARIANTS) {
		const start = library.flows[target].start[surface];
		if (!screenIds.has(start)) {
			errors.push(`flow ${target}/${surface}: start screen ${start} is not defined`);
		}
	}
	return errors;
}

function collectVariantErrors(variant: ReportFlowVariant): Array<string> {
	const errors: Array<string> = [];
	const name = `flow ${variant.target}/${variant.surface}`;
	if (variant.screens.get(variant.startScreenId)?.kind === 'info') {
		errors.push(`${name}: the start screen must not be an info screen`);
	}
	for (const screen of variant.screens.values()) {
		if (screen.kind === 'choice' && !screen.options.some((option) => option.outcome.type !== 'link')) {
			errors.push(`${name} screen ${screen.def.id}: no option that is not a link remains`);
		}
		for (const outcome of getScreenOutcomes(screen)) {
			if (outcome.type === 'submit') {
				checkLegacyCategory(outcome.reason, variant.target, `${name} screen ${screen.def.id}`, errors);
			}
		}
		for (const item of screen.def.checklist?.items ?? []) {
			if (item.reason !== undefined) {
				checkLegacyCategory(item.reason, variant.target, `${name} screen ${screen.def.id}`, errors);
			}
		}
	}
	const depth = new Map<string, number>();
	const visiting = new Set<string>();
	const measure = (screenId: string): number => {
		const known = depth.get(screenId);
		if (known !== undefined) {
			return known;
		}
		if (visiting.has(screenId)) {
			errors.push(`${name}: cycle through screen ${screenId}`);
			return Number.POSITIVE_INFINITY;
		}
		visiting.add(screenId);
		const screen = variant.screens.get(screenId);
		let longest = 0;
		for (const next of screen ? getScreenEdges(screen) : []) {
			longest = Math.max(longest, measure(next));
		}
		visiting.delete(screenId);
		depth.set(screenId, longest + 1);
		return longest + 1;
	};
	const longestWalk = measure(variant.startScreenId);
	if (Number.isFinite(longestWalk) && longestWalk > MAX_WALK_SCREENS) {
		errors.push(`${name}: longest walk is ${longestWalk} screens, the limit is ${MAX_WALK_SCREENS}`);
	}
	return errors;
}

function checkLegacyCategory(reason: string, target: ReportFlowTargetType, where: string, errors: Array<string>) {
	if (!isReportReasonKey(reason) || !getLegacyCategory(reason, target)) {
		errors.push(`${where}: reason ${reason} has no legacy category for ${target}`);
	}
}

function assertNoDefinitionErrors(errors: Array<string>): void {
	if (errors.length > 0) {
		throw new Error(`Invalid report flow definitions:\n${[...new Set(errors)].join('\n')}`);
	}
}

export function assertValidReportFlowLibrary(library: ReportFlowLibrary): void {
	const errors = collectDefinitionErrors(library);
	assertNoDefinitionErrors(errors);
	const reachable = new Set<string>();
	for (const instance of REPORT_FLOW_CHECKED_INSTANCES) {
		for (const {target, surface} of REPORT_FLOW_VARIANTS) {
			const variant = buildReportFlowVariant(library, target, surface, instance);
			errors.push(...collectVariantErrors(variant));
			for (const screenId of variant.screens.keys()) {
				reachable.add(screenId);
			}
		}
	}
	for (const screen of library.screens) {
		if (!reachable.has(screen.id)) {
			errors.push(`screen ${screen.id}: not reachable from any flow`);
		}
	}
	assertNoDefinitionErrors(errors);
}