emdash 0.39.0 → 0.40.0

package/src/seed/validate.ts

@@ -5,13 +5,14 @@
  */
 
 import { getI18nConfig, resolveConfiguredLocale } from "../i18n/config.js";
+import { validateBlockFields } from "../schema/block-type-contract.js";
 import {
 	FIELD_TYPES,
 	isIndexableFieldType,
 	MAX_COLLECTION_GROUP_LENGTH,
 	MAX_COLLECTION_LIST_COLUMNS,
 } from "../schema/types.js";
-import type { SeedFile, SeedMenuItem, ValidationResult } from "./types.js";
+import type { SeedFile, SeedMenuItem, SeedTaxonomy, ValidationResult } from "./types.js";
 
 const COLLECTION_FIELD_SLUG_PATTERN = /^[a-z][a-z0-9_]*$/;
 const SLUG_PATTERN = /^[a-z0-9-]+$/;
@@ -35,6 +36,41 @@ function isValidRedirectPath(path: string): boolean {
 	}
 }
 
+/**
+ * The entry that declares `taxonomy`'s `hierarchical` and `collections`: the last
+ * entry of its `translationOf` chain within the taxonomy's name, or undefined when
+ * the chain loops.
+ */
+export function findTaxonomyStructureSource<T extends Pick<SeedTaxonomy, "name" | "translationOf">>(
+	taxonomy: T,
+	taxonomiesById: ReadonlyMap<string, T>,
+): T | undefined {
+	const visited = new Set<T>();
+	let current = taxonomy;
+	while (!visited.has(current)) {
+		visited.add(current);
+		const source = current.translationOf ? taxonomiesById.get(current.translationOf) : undefined;
+		if (!source || source.name !== current.name) return current;
+		current = source;
+	}
+	return undefined;
+}
+
+/** Whether `a` and `b` disagree on `hierarchical` or `collections`, comparing only fields both declare. */
+function declaresDifferentStructure(a: SeedTaxonomy, b: SeedTaxonomy): boolean {
+	if (
+		a.hierarchical !== undefined &&
+		b.hierarchical !== undefined &&
+		a.hierarchical !== b.hierarchical
+	) {
+		return true;
+	}
+	if (!Array.isArray(a.collections) || !Array.isArray(b.collections)) return false;
+	const own = new Set(a.collections);
+	const other = new Set(b.collections);
+	return own.size !== other.size || [...own].some((collection) => !other.has(collection));
+}
+
 /**
  * Validate a seed file
  *
@@ -81,6 +117,49 @@ export function validateSeed(data: unknown): ValidationResult {
 		}
 	}
 
+	if (seed.blockTypes !== undefined) {
+		if (!Array.isArray(seed.blockTypes)) {
+			errors.push("blockTypes must be an array");
+		} else {
+			const slugs = new Set<string>();
+			for (const [index, blockType] of seed.blockTypes.entries()) {
+				const prefix = `blockTypes[${index}]`;
+				if (!blockType.slug || !COLLECTION_FIELD_SLUG_PATTERN.test(blockType.slug)) {
+					errors.push(`${prefix}.slug: must be a valid block type slug`);
+				} else if (slugs.has(blockType.slug)) {
+					errors.push(`${prefix}.slug: duplicate block type slug "${blockType.slug}"`);
+				} else {
+					slugs.add(blockType.slug);
+				}
+				if (!blockType.label) errors.push(`${prefix}.label: is required`);
+				if (!Array.isArray(blockType.versions) || blockType.versions.length === 0) {
+					errors.push(`${prefix}.versions: must be a non-empty array`);
+					continue;
+				}
+				const numbers = blockType.versions.map((version) => version.version);
+				const sorted = [...numbers].toSorted((left, right) => left - right);
+				if (
+					sorted[0] !== 1 ||
+					sorted.some((version, versionIndex) => version !== versionIndex + 1)
+				) {
+					errors.push(`${prefix}.versions: numbers must be contiguous and start at 1`);
+				}
+				if (!numbers.includes(blockType.currentVersion)) {
+					errors.push(`${prefix}.currentVersion: must name a declared version`);
+				}
+				for (const [versionIndex, version] of blockType.versions.entries()) {
+					try {
+						validateBlockFields(version.fields);
+					} catch (error) {
+						errors.push(
+							`${prefix}.versions[${versionIndex}].${error instanceof Error ? error.message : "invalid fields"}`,
+						);
+					}
+				}
+			}
+		}
+	}
+
 	// Validate collections
 	if (seed.collections) {
 		if (!Array.isArray(seed.collections)) {
@@ -218,6 +297,11 @@ export function validateSeed(data: unknown): ValidationResult {
 			errors.push("taxonomies must be an array");
 		} else {
 			const taxonomyNames = new Set<string>();
+			const taxonomiesById = new Map<string, SeedTaxonomy>();
+			for (const taxonomy of seed.taxonomies) {
+				if (taxonomy.id) taxonomiesById.set(taxonomy.id, taxonomy);
+			}
+			const structureDeclarations = new Map<string, SeedTaxonomy>();
 
 			for (let i = 0; i < seed.taxonomies.length; i++) {
 				const taxonomy = seed.taxonomies[i];
@@ -243,18 +327,58 @@ export function validateSeed(data: unknown): ValidationResult {
 					errors.push(`${prefix}: label is required`);
 				}
 
-				if (taxonomy.hierarchical === undefined) {
+				const structureSource = findTaxonomyStructureSource(taxonomy, taxonomiesById);
+
+				// A translation takes its taxonomy's structure, so it may omit both, but only
+				// from an entry of the same taxonomy.
+				if (
+					taxonomy.translationOf &&
+					(taxonomy.hierarchical === undefined || taxonomy.collections === undefined)
+				) {
+					if (!structureSource) {
+						errors.push(
+							`${prefix}.translationOf: the translationOf chain from "${taxonomy.translationOf}" loops, so hierarchical and collections are required`,
+						);
+					} else if (structureSource === taxonomy) {
+						errors.push(
+							`${prefix}.translationOf: "${taxonomy.translationOf}" is not an entry of taxonomy "${taxonomy.name}", so hierarchical and collections are required`,
+						);
+					}
+				}
+
+				if (taxonomy.hierarchical === undefined && !taxonomy.translationOf) {
 					errors.push(`${prefix}: hierarchical is required`);
 				}
 
-				if (!Array.isArray(taxonomy.collections)) {
+				if (taxonomy.collections === undefined) {
+					if (!taxonomy.translationOf) errors.push(`${prefix}.collections: must be an array`);
+				} else if (!Array.isArray(taxonomy.collections)) {
 					errors.push(`${prefix}.collections: must be an array`);
-				} else if (taxonomy.collections.length === 0) {
+				} else if (taxonomy.collections.length === 0 && !taxonomy.translationOf) {
 					warnings.push(
 						`${prefix}.collections: taxonomy "${taxonomy.name}" is not assigned to any collections`,
 					);
 				}
 
+				if (structureSource && structureSource !== taxonomy) {
+					if (declaresDifferentStructure(taxonomy, structureSource)) {
+						warnings.push(
+							`${prefix}: hierarchical and collections come from taxonomies[${seed.taxonomies.indexOf(structureSource)}], so the values declared here are ignored`,
+						);
+					}
+				} else if (structureSource && taxonomy.name) {
+					const declaring = structureDeclarations.get(taxonomy.name);
+					if (!declaring) {
+						structureDeclarations.set(taxonomy.name, taxonomy);
+					} else if (declaresDifferentStructure(taxonomy, declaring)) {
+						warnings.push(
+							`${prefix}: hierarchical and collections differ from taxonomies[${seed.taxonomies.indexOf(declaring)}]; every locale of taxonomy "${taxonomy.name}" shares them, so only one entry's values apply`,
+						);
+					}
+				}
+
+				const hierarchical = (structureSource ?? taxonomy).hierarchical;
+
 				// Validate terms if present
 				if (taxonomy.terms) {
 					if (!Array.isArray(taxonomy.terms)) {
@@ -288,9 +412,9 @@ export function validateSeed(data: unknown): ValidationResult {
 							}
 
 							// Check parent reference validity (for hierarchical taxonomies)
-							if (term.parent && taxonomy.hierarchical) {
+							if (term.parent && hierarchical) {
 								// Parent will be validated in a second pass
-							} else if (term.parent && !taxonomy.hierarchical) {
+							} else if (term.parent && !hierarchical) {
 								warnings.push(
 									`${termPrefix}.parent: taxonomy "${taxonomy.name}" is not hierarchical, parent will be ignored`,
 								);
@@ -298,7 +422,7 @@ export function validateSeed(data: unknown): ValidationResult {
 						}
 
 						// Second pass: validate parent references (within the same locale).
-						if (taxonomy.hierarchical && taxonomy.terms) {
+						if (hierarchical && taxonomy.terms) {
 							for (let j = 0; j < taxonomy.terms.length; j++) {
 								const term = taxonomy.terms[j];
 								const termLocale = resolveConfiguredLocale(

package/src/settings/index.ts

@@ -12,6 +12,7 @@ import { siteSettingsTag } from "../cache/chrome-tags.js";
 import { resolvePluginEncryptionKeys } from "../config/secrets.js";
 import { MediaRepository } from "../database/repositories/media.js";
 import { OptionsRepository } from "../database/repositories/options.js";
+import { withTransaction } from "../database/transaction.js";
 import type { Database } from "../database/types.js";
 import { getDb } from "../loader.js";
 import { cachedQuery, invalidateObjectCache } from "../object-cache/index.js";
@@ -32,7 +33,13 @@ import {
 	invalidateSingleFlightCache,
 	singleFlightCached,
 } from "../utils/single-flight-cache.js";
-import type { SiteSettings, SiteSettingKey, MediaReference, SeoSettings } from "./types.js";
+import type {
+	MediaReference,
+	SeoSettings,
+	SiteSettings,
+	SiteSettingsUpdate,
+	SiteSettingKey,
+} from "./types.js";
 
 /** Prefix for site settings in the options table */
 const SETTINGS_PREFIX = "site:";
@@ -349,21 +356,37 @@ export async function getSiteSettingsWithDb(
  * ```
  */
 export async function setSiteSettings(
-	settings: Partial<SiteSettings>,
+	settings: SiteSettingsUpdate,
 	db: Kysely<Database>,
 ): Promise<void> {
-	const options = new OptionsRepository(db);
-
-	// Convert settings to options format
 	const updates: Record<string, unknown> = {};
+	const deletions: string[] = [];
+	const seo = settings.seo;
+
 	for (const [key, value] of Object.entries(settings)) {
-		if (value !== undefined) {
-			updates[`${SETTINGS_PREFIX}${key}`] = value;
-		}
+		if (value === undefined || (key === "seo" && seo?.defaultOgImage === null)) continue;
+		if (value === null) deletions.push(`${SETTINGS_PREFIX}${key}`);
+		else updates[`${SETTINGS_PREFIX}${key}`] = value;
 	}
 
 	try {
-		await options.setMany(updates);
+		await withTransaction(db, async (trx) => {
+			const transactionOptions = new OptionsRepository(trx);
+			await transactionOptions.setMany(updates);
+			await transactionOptions.deleteMany(deletions);
+
+			if (seo?.defaultOgImage === null) {
+				const existingSeo =
+					(await transactionOptions.get<SeoSettings>(`${SETTINGS_PREFIX}seo`)) ?? {};
+				const nextSeo = { ...existingSeo, ...seo };
+				delete nextSeo.defaultOgImage;
+				if (Object.keys(nextSeo).length === 0) {
+					await transactionOptions.delete(`${SETTINGS_PREFIX}seo`);
+				} else {
+					await transactionOptions.set(`${SETTINGS_PREFIX}seo`, nextSeo);
+				}
+			}
+		});
 	} finally {
 		invalidateSiteSettingsCache();
 	}

package/src/settings/types.ts

@@ -80,5 +80,20 @@ export interface SiteSettings {
 	seo?: SeoSettings;
 }
 
+/** Partial SEO update. `null` removes the configured default image. */
+export interface SeoSettingsUpdate extends Omit<SeoSettings, "defaultOgImage"> {
+	defaultOgImage?: MediaReference | null;
+}
+
+/** Site-settings write shape. `null` removes media references; omitted fields are unchanged. */
+export interface SiteSettingsUpdate extends Omit<
+	Partial<SiteSettings>,
+	"logo" | "favicon" | "seo"
+> {
+	logo?: MediaReference | null;
+	favicon?: MediaReference | null;
+	seo?: SeoSettingsUpdate;
+}
+
 /** Keys that are valid site settings */
 export type SiteSettingKey = keyof SiteSettings;

package/src/taxonomies/index.ts

@@ -13,6 +13,10 @@
 import { sql, type Kysely } from "kysely";
 
 import { taxonomyTag } from "../cache/chrome-tags.js";
+import {
+	parseTaxonomyCollections,
+	selectTaxonomyDefs,
+} from "../database/repositories/taxonomy-def.js";
 import type { Database } from "../database/types.js";
 import { validateIdentifier } from "../database/validate.js";
 import { getI18nConfig } from "../i18n/config.js";
@@ -101,7 +105,8 @@ export function invalidateTermCache(): void {
 }
 
 /**
- * Worker-isolate cache for taxonomy definitions, keyed by resolved locale.
+ * Worker-isolate cache for taxonomy definitions: every locale's rows, resolved
+ * per locale in memory.
  *
  * Taxonomy *definitions* (the "category"/"tag" taxonomies themselves, not
  * their terms) are read on every public render that hydrates entry terms —
@@ -125,8 +130,8 @@ export function invalidateTermCache(): void {
  */
 interface TaxonomyDefsHolder {
 	version: number;
-	/** locale key ("*" for "all locales") → { version it was fetched at, promise }. */
-	cache: Map<string, { version: number; promise: Promise<TaxonomyDef[]> }>;
+	/** The rows and the version they were fetched at. */
+	cache: Map<"all", { version: number; promise: Promise<TaxonomyDef[]> }>;
 }
 
 const TAXONOMY_DEFS_CACHE_KEY = Symbol.for("emdash:taxonomy-defs");
@@ -164,118 +169,103 @@ export function resetTaxonomyDefsCacheForTests(): void {
 	defsHolder.cache.clear();
 }
 
-/**
- * Fetch taxonomy definitions straight from the database (no caching).
- */
-async function fetchTaxonomyDefs(locale: string | undefined): Promise<TaxonomyDef[]> {
+/** Every locale's definition rows, straight from the database (no caching). */
+async function fetchTaxonomyDefRows(): Promise<TaxonomyDef[]> {
 	const db = await getDb();
-	let query = db.selectFrom("_emdash_taxonomy_defs").selectAll();
-	if (locale !== undefined) query = query.where("locale", "=", locale);
-	const rows = await query.execute();
+	const rows = await selectTaxonomyDefs(db)
+		.orderBy("d.name", "asc")
+		.orderBy("d.locale", "asc")
+		.execute();
 	return rows.map(rowToTaxonomyDef);
 }
 
 /**
- * Resolve taxonomy defs through the isolate fallback cache, bypassing it for
- * isolated databases. The returned promise is cached (not the resolved value)
- * so concurrent cold-isolate readers share one in-flight query; a rejection
- * evicts the entry so the next caller retries.
+ * Resolve the definition rows through the isolate fallback cache, bypassing it
+ * for isolated databases. The returned promise is cached (not the resolved
+ * value) so concurrent cold-isolate readers share one in-flight query; a
+ * rejection evicts the entry so the next caller retries.
  */
-function loadTaxonomyDefs(localeKey: string, locale: string | undefined): Promise<TaxonomyDef[]> {
+function loadTaxonomyDefRows(): Promise<TaxonomyDef[]> {
 	if (getRequestContext()?.dbIsIsolated === true) {
-		return fetchTaxonomyDefs(locale);
+		return fetchTaxonomyDefRows();
 	}
-	const existing = defsHolder.cache.get(localeKey);
+	const existing = defsHolder.cache.get("all");
 	if (existing && existing.version === defsHolder.version) {
 		return existing.promise;
 	}
 	const version = defsHolder.version;
-	const promise = fetchTaxonomyDefs(locale).catch((error: unknown) => {
-		const current = defsHolder.cache.get(localeKey);
+	const promise = fetchTaxonomyDefRows().catch((error: unknown) => {
+		const current = defsHolder.cache.get("all");
 		if (current && current.promise === promise) {
-			defsHolder.cache.delete(localeKey);
+			defsHolder.cache.delete("all");
 		}
 		throw error;
 	});
-	defsHolder.cache.set(localeKey, { version, promise });
+	defsHolder.cache.set("all", { version, promise });
 	return promise;
 }
 
 /**
- * Get every taxonomy definition. Definitions are per-locale (one row per
- * locale inside the same translation_group) — by default we resolve to the
- * active locale.
- *
- * Two-tier cache: per-request via `requestCached` (so a single render that
- * hydrates terms for several collections pays at most one call), then
- * per-isolate via the global holder (so warm renders issue zero queries).
- * The `requestCached` key is unchanged so `getTaxonomyDef`'s peek still hits.
+ * Every locale's definition rows. Two-tier cache: per-request via
+ * `requestCached`, then the object cache when configured, else the isolate
+ * holder, so warm renders issue zero queries whatever locale they ask for.
  */
-export async function getTaxonomyDefs(options: TaxonomyQueryOptions = {}): Promise<TaxonomyDef[]> {
-	const locale = resolveLocale(options.locale);
-	const localeKey = locale ?? "*";
-	return requestCached(`taxonomy-defs:${localeKey}`, async () => {
+function getTaxonomyDefRows(): Promise<TaxonomyDef[]> {
+	return requestCached("taxonomy-def-rows", async () => {
 		if (await isObjectCacheActive()) {
 			return cachedQuery({
 				namespace: CacheNamespace.TAXONOMIES,
-				key: `defs:${localeKey}`,
-				load: () => fetchTaxonomyDefs(locale),
+				key: "defRows",
+				load: fetchTaxonomyDefRows,
 			});
 		}
-		return loadTaxonomyDefs(localeKey, locale);
+		return loadTaxonomyDefRows();
 	});
 }
 
 /**
- * Get a single taxonomy definition by name. Uses the fallback chain so even
- * if there is no translation for the active locale we still return something.
- *
- * If `getTaxonomyDefs()` has already loaded the full list in this request
- * (which happens during entry-term hydration on every page that renders a
- * collection), search the matching def in memory rather than running a
- * second query against `_emdash_taxonomy_defs`.
+ * One definition per taxonomy, in the first locale of `chain` that has one.
+ * A taxonomy with no definition anywhere on the chain still resolves, to its
+ * default-locale row or else its lowest locale: its structure is the same in
+ * every locale, and only the label falls back.
  */
-export async function getTaxonomyDef(
-	name: string,
-	options: TaxonomyQueryOptions = {},
-): Promise<TaxonomyDef | null> {
-	const chain = resolveLocaleChain(options.locale);
-	const peekKey = `taxonomy-defs:${resolveLocale(options.locale) ?? "*"}`;
-	const allDefs = peekRequestCache<TaxonomyDef[]>(peekKey);
-	if (allDefs) {
-		const defs = await allDefs;
-		if (chain.length === 0) return defs.find((d) => d.name === name) ?? null;
-		for (const locale of chain) {
-			const found = defs.find((d) => d.name === name && d.locale === locale);
-			if (found) return found;
-		}
-		return null;
+function resolveDefs(rows: readonly TaxonomyDef[], chain: readonly string[]): TaxonomyDef[] {
+	const defaultLocale = getI18nConfig()?.defaultLocale;
+	const preference = defaultLocale === undefined ? chain : [...chain, defaultLocale];
+	const byName = new Map<string, TaxonomyDef>();
+	for (const row of rows) {
+		const current = byName.get(row.name);
+		if (!current || rank(row.locale) < rank(current.locale)) byName.set(row.name, row);
 	}
+	return [...byName.values()];
 
-	return requestCached(`taxonomy-def:${name}:${chain.join(",")}`, async () => {
-		const db = await getDb();
+	function rank(locale: string): number {
+		const index = preference.indexOf(locale);
+		return index === -1 ? preference.length : index;
+	}
+}
 
-		if (chain.length === 0) {
-			const row = await db
-				.selectFrom("_emdash_taxonomy_defs")
-				.selectAll()
-				.where("name", "=", name)
-				.orderBy("locale", "asc")
-				.executeTakeFirst();
-			return row ? rowToTaxonomyDef(row) : null;
-		}
+/**
+ * Get every taxonomy definition, one per taxonomy, labelled for the active
+ * locale (see `resolveDefs` for the fallback).
+ */
+export async function getTaxonomyDefs(options: TaxonomyQueryOptions = {}): Promise<TaxonomyDef[]> {
+	const chain = resolveLocaleChain(options.locale);
+	return requestCached(`taxonomy-defs:${chain.join(",")}`, async () =>
+		resolveDefs(await getTaxonomyDefRows(), chain),
+	);
+}
 
-		for (const locale of chain) {
-			const row = await db
-				.selectFrom("_emdash_taxonomy_defs")
-				.selectAll()
-				.where("name", "=", name)
-				.where("locale", "=", locale)
-				.executeTakeFirst();
-			if (row) return rowToTaxonomyDef(row);
-		}
-		return null;
-	});
+/**
+ * Get a single taxonomy definition by name, labelled for the active locale.
+ * Resolves whenever the taxonomy is defined in any locale (see `resolveDefs`).
+ */
+export async function getTaxonomyDef(
+	name: string,
+	options: TaxonomyQueryOptions = {},
+): Promise<TaxonomyDef | null> {
+	const defs = await getTaxonomyDefs(options);
+	return defs.find((def) => def.name === name) ?? null;
 }
 
 /**
@@ -412,8 +402,7 @@ function getVisibleTermCounts(
 	collections: string[],
 	locale?: string,
 ): Promise<Map<string, number>> {
-	// The collection scope is part of the key: per-locale rows of the same def
-	// can drift in their declared collections, and a caller may pass a narrower
+	// The collection scope is part of the key: a caller may pass a narrower
 	// scope. Identical inputs (the widget + term-page hot path) still share one
 	// entry.
 	const scope = [...new Set(collections)].toSorted().join(",");
@@ -855,7 +844,7 @@ function rowToTaxonomyDef(row: {
 		label: row.label,
 		labelSingular: row.label_singular ?? undefined,
 		hierarchical: row.hierarchical === 1,
-		collections: row.collections ? JSON.parse(row.collections) : [],
+		collections: parseTaxonomyCollections(row.collections),
 		locale: row.locale,
 		translationGroup: row.translation_group,
 	};

package/src/transfer/analyze/index.ts

@@ -0,0 +1,45 @@
+export type { IssueState } from "./issues.js";
+
+export type { PlanInputs, PlanOrigin, PlanTarget, PrincipalBylines } from "./plan.js";
+export { applyDecisions, buildBlockedPlan, buildPlan, defaultDecisions } from "./plan.js";
+
+export type { AnalyzeImportStepInput, AnalyzeImportStepResult, FinalizePlanInput } from "./step.js";
+export { analyzeImportStep, finalizePlan, loadImportPlan } from "./step.js";
+
+export type { AnalysisTargetContext, DomainFindings } from "./target.js";
+export {
+	analysisTargetContext,
+	checkLocales,
+	findMissingUsers,
+	findRedirectLoops,
+	inspectTargetDomain,
+	MAX_LOOP_CHECKED_REDIRECTS,
+	suggestPrincipalUsers,
+} from "./target.js";
+
+export type {
+	PrincipalSummary,
+	ValidateStagedPackageInput,
+	ValidationOptions,
+	ValidationPhase,
+	ValidationState,
+	ValidationStepResult,
+	ValidationSummary,
+	ValidationTarget,
+} from "./validate.js";
+export {
+	initialValidationState,
+	parseValidationState,
+	runValidationStep,
+	summarizeValidation,
+	validateStagedPackage,
+	validateStagedPackageStep,
+	VALIDATION_PHASES,
+	validationStateSchema,
+} from "./validate.js";
+
+export type { FieldInfo, RecordScan, TargetDialect } from "./values.js";
+export { checkEntryFields, checkRecordNumbers, scanRecordValues } from "./values.js";
+
+export type { KeyedRecord, UniqueCollision, UniqueConstraint, UniqueKey } from "./unique-keys.js";
+export { findUniqueCollisions, UNIQUE_CONSTRAINTS, uniqueKeysOf } from "./unique-keys.js";

package/src/transfer/analyze/issues.ts

@@ -0,0 +1,55 @@
+/**
+ * Bounded blocker and warning lists for analysis.
+ *
+ * Issue messages are fixed strings and details carry only locations (package
+ * paths, line numbers, property names, record kinds and ids) — never record
+ * values. Package content is untrusted and plans, errors, and logs are shown
+ * to people who did not necessarily write the package.
+ */
+
+import { z } from "zod";
+
+import { TRANSFER_LIMITS } from "../format/limits.js";
+import {
+	planBlockerSchema,
+	planWarningSchema,
+	type PlanBlocker,
+	type PlanWarning,
+} from "../format/plan.js";
+
+export const issueStateSchema = z.strictObject({
+	blockers: z.array(planBlockerSchema),
+	warnings: z.array(planWarningSchema),
+	droppedBlockers: z.number().int().nonnegative(),
+	droppedWarnings: z.number().int().nonnegative(),
+});
+
+export type IssueState = z.infer<typeof issueStateSchema>;
+
+export function emptyIssues(): IssueState {
+	return { blockers: [], warnings: [], droppedBlockers: 0, droppedWarnings: 0 };
+}
+
+export function addBlocker(issues: IssueState, blocker: PlanBlocker): void {
+	if (issues.blockers.length < TRANSFER_LIMITS.planIssues) issues.blockers.push(blocker);
+	else issues.droppedBlockers++;
+}
+
+export function addWarning(issues: IssueState, warning: PlanWarning): void {
+	if (issues.warnings.length < TRANSFER_LIMITS.planIssues) issues.warnings.push(warning);
+	else issues.droppedWarnings++;
+}
+
+/** The warnings plus an `issues_truncated` warning when either list overflowed. */
+export function finalWarnings(issues: IssueState): PlanWarning[] {
+	if (issues.droppedBlockers === 0 && issues.droppedWarnings === 0) return [...issues.warnings];
+	return [
+		...issues.warnings,
+		{
+			code: "issues_truncated",
+			message: "More issues were found than the plan lists",
+			count: issues.droppedBlockers + issues.droppedWarnings,
+			detail: { blockers: issues.droppedBlockers, warnings: issues.droppedWarnings },
+		},
+	];
+}