@growth-labs/cms 0.5.29 → 0.5.30

package/src/engine/validator/checks/source-section-diagnostics.ts

@@ -0,0 +1,187 @@
+/**
+ * Source-section diagnostics (#329).
+ *
+ * These run against markdown that has ALREADY been through
+ * `normalizeSourceSections()`. That ordering is the whole point: the
+ * normalizer fixes everything mechanically fixable, so anything still present
+ * here needs an editor's judgement rather than another rewrite — and each of
+ * these is a proven render breaker, which is why they block publish.
+ *
+ * Draft autosave stays allowed regardless; an editor must never lose work to a
+ * formatting complaint.
+ */
+import { normalizeSourceSections } from '../../source-sections.js'
+import type {
+	ArticleBodyInput,
+	ValidationError,
+	ValidationErrorCode,
+	ValidationSpan,
+} from '../types.js'
+import { makeError } from '../types.js'
+
+export interface SourceSectionOptions {
+	/** Escalate these diagnostics from warn to block. Publish sets this. */
+	blockSourceSectionDefects?: boolean
+}
+
+const NBSP = ' '
+const MANUAL_BULLET = /^\s*[●•▪]/u
+const LINK = /\[([^\]]*)\]\(([^)]*)\)/g
+
+interface SectionLine {
+	text: string
+	/** Byte offset of this line in the source document. */
+	start: number
+}
+
+/** Lines inside every Sources/References section, with document offsets. */
+function collectSectionLines(source: string): SectionLine[] {
+	const lines = source.split('\n')
+	const collected: SectionLine[] = []
+	let offset = 0
+	let sectionLevel: number | null = null
+
+	for (const text of lines) {
+		const heading = /^(#{1,6})\s+(.*)$/.exec(text)
+		const level = heading ? (heading[1]?.length ?? 0) : null
+
+		if (sectionLevel !== null && level !== null && level <= sectionLevel) {
+			sectionLevel = null
+		}
+
+		if (sectionLevel !== null) {
+			collected.push({ text, start: offset })
+		} else if (level !== null) {
+			const word = (heading?.[2] ?? '')
+				.replace(/[*_]/g, '')
+				.replace(/\s*:\s*$/, '')
+				.trim()
+			if (/^(sources|references)$/i.test(word)) sectionLevel = level
+		}
+
+		offset += text.length + 1
+	}
+
+	return collected
+}
+
+function isFormattingOnly(text: string): boolean {
+	if (text.trim() === '') return false
+	return (
+		text
+			.replaceAll(NBSP, ' ')
+			.replace(/[*_~`#]/g, '')
+			.trim() === ''
+	)
+}
+
+/** Emphasis delimiters wrapping the entire label, e.g. `[**t**](u)`. */
+function hasWholeLabelEmphasis(label: string): boolean {
+	const match = /^(\*\*|__|\*|_)([\s\S]+)\1$/.exec(label.trim())
+	if (!match) return false
+	return !(match[2] ?? '').includes(match[1] as string)
+}
+
+/** An odd number of `**` or `*` runs — ambiguous, so the normalizer left it. */
+function hasUnbalancedEmphasis(label: string): boolean {
+	const strong = (label.match(/\*\*/g) ?? []).length
+	if (strong % 2 !== 0) return true
+	const em = (label.replace(/\*\*/g, '').match(/\*/g) ?? []).length
+	if (em % 2 !== 0) return true
+	const under = (label.match(/__/g) ?? []).length
+	return under % 2 !== 0
+}
+
+export function check(
+	input: ArticleBodyInput,
+	options: SourceSectionOptions = {},
+): ValidationError[] {
+	// Warn on save, block on publish. The design keeps draft autosave working
+	// so an editor cannot lose work to a formatting complaint, while still
+	// refusing to publish a section that is a proven render breaker.
+	const escalate = options.blockSourceSectionDefects === true
+	const report = (
+		code: ValidationErrorCode,
+		message: string,
+		span?: ValidationSpan,
+	): ValidationError => {
+		const error = makeError(code, message, span)
+		return escalate ? { ...error, severity: 'block' } : error
+	}
+
+	if (!input.body_markdown) return []
+
+	// Report against normalized text so a defect the normalizer would have
+	// fixed is never surfaced to the editor as their problem.
+	const source = normalizeSourceSections(input.body_markdown).markdown
+	const errors: ValidationError[] = []
+	const lines = collectSectionLines(source)
+
+	let linkLike = 0
+	let listItems = 0
+
+	for (const { text, start } of lines) {
+		const span = { start, end: start + text.length }
+
+		if (MANUAL_BULLET.test(text)) {
+			errors.push(
+				report(
+					'source-section-manual-bullet',
+					`This source line still starts with a manual bullet character. Replace it with "- " so it renders as one list, not separate paragraphs.`,
+					span,
+				),
+			)
+		}
+
+		if (isFormattingOnly(text)) {
+			errors.push(
+				report(
+					'source-section-formatting-only-line',
+					`This line contains only formatting characters and renders as an empty heading. Delete it.`,
+					span,
+				),
+			)
+		}
+
+		if (/^\s*[-*+]\s+/.test(text)) listItems++
+
+		for (const link of text.matchAll(LINK)) {
+			const label = link[1] ?? ''
+			if (label.trim() !== '') linkLike++
+
+			if (hasWholeLabelEmphasis(label)) {
+				errors.push(
+					report(
+						'source-section-wrapped-link-label',
+						`The link title "${label.trim()}" is wrapped in emphasis markers, which stay visible inside the link. Remove the surrounding * or _ characters.`,
+						span,
+					),
+				)
+			} else if (hasUnbalancedEmphasis(label)) {
+				errors.push(
+					report(
+						'source-section-unbalanced-emphasis',
+						`The link title "${label.trim()}" has an unmatched emphasis marker. Close it or remove it — it cannot be corrected automatically without changing the title.`,
+						span,
+					),
+				)
+			}
+		}
+	}
+
+	// A section that reads as a list of sources but has no list items at all
+	// renders as a run of paragraphs. Only claim this when there is something
+	// list-shaped to talk about.
+	if (listItems === 0 && linkLike > 1) {
+		const first = lines[0]
+		errors.push(
+			report(
+				'source-section-unlistable',
+				`This source section has ${linkLike} links but no list items, so it renders as separate paragraphs. Start each source line with "- ".`,
+				first ? { start: first.start, end: first.start + first.text.length } : undefined,
+			),
+		)
+	}
+
+	return errors
+}

package/src/engine/validator/index.ts

@@ -21,6 +21,7 @@ import * as iframeMissingDims from './checks/iframe-missing-dims-and-wrapper.js'
 import * as invisibleControl from './checks/invisible-control-chars.js'
 import * as paywallMarker from './checks/paywall-marker-leak.js'
 import * as rawBlockHtml from './checks/raw-block-html.js'
+import * as sourceSectionDiagnostics from './checks/source-section-diagnostics.js'
 import * as unresolvedAnchor from './checks/unresolved-footnote-anchor.js'
 import * as wordGdocs from './checks/word-gdocs-paste-artifacts.js'
 
@@ -302,6 +303,7 @@ export const checkBareUrlNotAutolinked = bareUrl.check
 export const checkEmptyAltText = emptyAlt.check
 export const checkIframeMissingDimsAndWrapper = iframeMissingDims.check
 export const checkHeadingHierarchySkip = headingHierarchy.check
+export const checkSourceSectionDiagnostics = sourceSectionDiagnostics.check
 export const checkPaywallMarkerLeak = paywallMarker.check
 
 /* -------------------------------------------------------------------------- */
@@ -310,11 +312,20 @@ export const checkPaywallMarkerLeak = paywallMarker.check
 
 export interface RunOptions extends ValidatorOptions {
 	requireBody: boolean
+	/**
+	 * Escalate source-section diagnostics (#329) from warn to block.
+	 *
+	 * Defaults to false so a draft save is never rejected for formatting — the
+	 * PATCH route returns 422 on any block-severity error. Publish call sites
+	 * set it to true, which is where the design wants these enforced.
+	 */
+	blockSourceSectionDefects: boolean
 }
 
 export const DEFAULT_RUN_OPTIONS: RunOptions = {
 	...DEFAULT_OPTIONS,
 	requireBody: true,
+	blockSourceSectionDefects: false,
 }
 
 /**
@@ -349,6 +360,7 @@ export function validateArticleBody(
 	errors.push(...checkEmptyAltText(input))
 	errors.push(...checkIframeMissingDimsAndWrapper(input))
 	errors.push(...checkHeadingHierarchySkip(input))
+	errors.push(...checkSourceSectionDiagnostics(input, opts))
 	errors.push(...checkPaywallMarkerLeak(input))
 	// Heuristic.
 	errors.push(...checkUnbalancedMarkdownEmphasis(input))

package/src/engine/validator/types.ts

@@ -55,6 +55,15 @@ export type ValidationErrorCode =
 	| 'heading-hierarchy-skip'
 	| 'paywall-marker-leak'
 	| 'stale-body-html'
+	// Source-section diagnostics (#329). Reported only for defects that
+	// SURVIVE normalizeSourceSections() — the normalizer already fixed
+	// everything mechanically fixable, so what is left needs an editor's
+	// judgement. Warn on save, block on publish; see SEVERITY below.
+	| 'source-section-manual-bullet'
+	| 'source-section-formatting-only-line'
+	| 'source-section-wrapped-link-label'
+	| 'source-section-unbalanced-emphasis'
+	| 'source-section-unlistable'
 
 export type ValidationResult = { ok: true } | { ok: false; errors: ValidationError[] }
 
@@ -88,6 +97,16 @@ export const SEVERITY: Readonly<Record<ValidationErrorCode, Severity>> = {
 	'heading-hierarchy-skip': 'warn',
 	'paywall-marker-leak': 'block',
 	'stale-body-html': 'block',
+	// #329. WARN by default so a draft save is never rejected — the design is
+	// explicit that an editor must not lose work to a formatting complaint, and
+	// the PATCH route returns 422 on any block-severity error. Publish call
+	// sites pass `blockSourceSectionDefects` to escalate these to block, which
+	// is where the design wants them enforced.
+	'source-section-manual-bullet': 'warn',
+	'source-section-formatting-only-line': 'warn',
+	'source-section-wrapped-link-label': 'warn',
+	'source-section-unbalanced-emphasis': 'warn',
+	'source-section-unlistable': 'warn',
 }
 
 export interface ValidatorOptions {

package/src/providers/types.ts

@@ -430,7 +430,7 @@ export interface SettingsProvider {
 }
 
 export interface SurveyProvider {
-	getResults(input: { surveyId: string }): Promise<SurveyResults>
+	getResults(input: { surveyId: string; offset?: number }): Promise<SurveyResults>
 	getCsv(input: { surveyId: string }): Promise<SurveyCsvResult>
 }
 

package/src/routes/content.ts

@@ -56,6 +56,7 @@ import {
 } from '../engine/revisions.js'
 import { applySlugRenameRedirects } from '../engine/slug-redirects.js'
 import { softDeleteContent } from '../engine/soft-delete.js'
+import { normalizeSourceSections } from '../engine/source-sections.js'
 import { TagInputError } from '../engine/taxonomy.js'
 import type { ValidationError } from '../engine/validator/index.js'
 import { parseLayoutEnvelope } from '../schema/layout.js'
@@ -1258,9 +1259,29 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 						bodyMarkdown?: string
 						bodyHtml?: string | null
 					}
-					const bodyMarkdown = articleContent.bodyMarkdown
-					const bodyHtml = articleContent.bodyHtml
+					let bodyMarkdown = articleContent.bodyMarkdown
+					let bodyHtml = articleContent.bodyHtml
 					const isDraft = existing.status === 'draft'
+
+					// Safe, deterministic Sources/References cleanup is applied before
+					// the body is persisted, so the stored Markdown is canonical and the
+					// editor's next read shows what will actually render (#329).
+					//
+					// When normalization changes the Markdown, any body_html the client
+					// sent alongside it was rendered from the pre-normalization text and
+					// is stale by construction. Persisting it would let the exact defect
+					// this fixes survive in the rendered output, which is how the
+					// original incident reached a published page — so it is dropped and
+					// re-rendered downstream.
+					if (typeof bodyMarkdown === 'string') {
+						const normalized = normalizeSourceSections(bodyMarkdown)
+						if (normalized.changed) {
+							bodyMarkdown = normalized.markdown
+							bodyHtml = null
+							articleContent.bodyMarkdown = normalized.markdown
+							articleContent.bodyHtml = null
+						}
+					}
 					if (bodyMarkdown !== undefined || bodyHtml !== undefined) {
 						const guard = evaluateArticleBody(
 							{ body_markdown: bodyMarkdown ?? null, body_html: bodyHtml ?? null },

package/src/routes/surveys.ts

@@ -28,9 +28,11 @@ export function createSurveyRoutes(config: SurveyRouteConfig): SurveyRouteHandle
 			if (denied) return withNoStoreAuthFailure(denied)
 			const surveyId = parseSurveyId(ctx)
 			if (!surveyId) return surveyErrorResponse('survey_invalid_request')
+			const offset = parseOffset(ctx)
+			if (offset === null) return surveyErrorResponse('survey_invalid_request')
 			try {
 				const parsed = SurveyResultsSchema.safeParse(
-					await providers.surveys?.getResults({ surveyId }),
+					await providers.surveys?.getResults({ surveyId, offset }),
 				)
 				if (!parsed.success || parsed.data.survey.id !== surveyId) {
 					return surveyErrorResponse('survey_provider_malformed')
@@ -70,6 +72,13 @@ async function requireSurveyAccess(authz: Authz, ctx: RouteContext): Promise<Res
 	return authz.requireRole('view_survey_responses' satisfies Capability, ctx)
 }
 
+function parseOffset(ctx: RouteContext): number | null {
+	const raw = new URL(ctx.request.url).searchParams.get('offset')
+	if (raw === null) return 0
+	const value = Number(raw)
+	return Number.isInteger(value) && value >= 0 ? value : null
+}
+
 function parseSurveyId(ctx: RouteContext): string | null {
 	const value = ctx.params.surveyId ?? ctx.params.id
 	const parsed = SurveyIdSchema.safeParse(value)
@@ -103,6 +112,8 @@ const ProviderFailureAllowlist = new Map<string, SurveyErrorCode>([
 	['404:survey_not_found', 'survey_not_found'],
 	['500:survey_internal_failure', 'survey_internal_failure'],
 	['502:survey_upstream_failure', 'survey_upstream_failure'],
+	['502:survey_upstream_auth_failed', 'survey_upstream_auth_failed'],
+	['502:survey_invalid_response', 'survey_invalid_response'],
 	['503:survey_provider_unavailable', 'survey_provider_unavailable'],
 	['503:survey_upstream_unavailable', 'survey_upstream_unavailable'],
 ])

package/src/surveys/access.ts

@@ -9,3 +9,12 @@ export const SURVEY_RESPONSE_ROLES: ReadonlySet<CmsRole> = new Set([
 export function canViewSurveyResponses(role: CmsRole | null | undefined): boolean {
 	return role != null && SURVEY_RESPONSE_ROLES.has(role)
 }
+
+// Aggregates are for anyone who can open the screen; individual answers and the
+// respondent attached to them are not. Splitting these lets a team see what
+// readers said in aggregate without exposing every member's words by name.
+export const SURVEY_VERBATIM_ROLES: ReadonlySet<CmsRole> = new Set(['owner', 'senior_editor'])
+
+export function canViewSurveyVerbatims(role: CmsRole | null | undefined): boolean {
+	return role != null && SURVEY_VERBATIM_ROLES.has(role)
+}

package/src/surveys/errors.ts

@@ -29,6 +29,18 @@ export const SURVEY_ERROR_DEFINITIONS = {
 		status: 502,
 		error: 'Survey reporting could not be loaded.',
 	},
+	// Distinct causes, distinct codes. These previously collapsed into
+	// survey_upstream_failure, so the screen showed one message for an auth
+	// rejection, an upstream outage, and a payload it could not parse — which is
+	// how a broken fetch receiver in a consuming host stayed invisible for a month.
+	survey_upstream_auth_failed: {
+		status: 502,
+		error: 'Survey reporting rejected this site\u2019s credentials.',
+	},
+	survey_invalid_response: {
+		status: 502,
+		error: 'Survey reporting returned a response we could not read.',
+	},
 	survey_internal_failure: {
 		status: 500,
 		error: 'Survey reporting could not be loaded.',

package/src/surveys/schema.ts

@@ -29,6 +29,11 @@ const BoundedRecordIdSchema = z
 	.regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/)
 const IsoTimestampSchema = z.string().datetime({ offset: true })
 const CountSchema = z.number().int().nonnegative().max(MAX_COUNT)
+const AnswerValueSchema = z.union([
+	z.string().max(MAX_FREE_TEXT_LENGTH),
+	z.number().int(),
+	z.array(z.string().max(MAX_OPTION_LENGTH)).max(MAX_CHOICE_OPTIONS),
+])
 const NonemptyBoundedStringSchema = z
 	.string()
 	.min(1)
@@ -208,6 +213,35 @@ export const SurveyResultsSchema = z
 						submittedAt: IsoTimestampSchema,
 						respondentSegment: SurveyRespondentSegmentSchema,
 						anonymous: z.boolean(),
+						// Opaque upstream contact handle. The host resolves its own member
+						// record from this; no email or name crosses the reporting boundary.
+						// Optional because the reporting upstream only emits these when the
+						// caller opts in. A consumer that always required them could not
+						// read a legacy payload, and this object is strict, so a consumer
+						// that never expected them discards the whole response.
+						contactId: BoundedRecordIdSchema.nullable().optional(),
+						// Host-enriched, optional. The consuming site joins contactId to its
+						// own member record and attaches a display label here; the reporting
+						// upstream never sees it. Absent means "not resolved", not "anonymous".
+						respondent: z
+							.object({
+								label: NonemptyBoundedStringSchema,
+								detail: z.string().max(MAX_OPTION_LENGTH).nullable().optional(),
+							})
+							.strict()
+							.nullable()
+							.optional(),
+						answers: z
+							.array(
+								z
+									.object({
+										questionId: SurveyQuestionIdSchema,
+										value: AnswerValueSchema,
+									})
+									.strict(),
+							)
+							.max(MAX_QUESTIONS)
+							.optional(),
 					})
 					.strict(),
 			)
@@ -256,6 +290,19 @@ export const SurveyResultsSchema = z
 		if (results.responses.length > results.survey.responseCount) {
 			ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Response rows exceed survey total' })
 		}
+		for (const [index, response] of results.responses.entries()) {
+			const seen = new Set<string>()
+			for (const [answerIndex, answer] of (response.answers ?? []).entries()) {
+				if (seen.has(answer.questionId)) {
+					ctx.addIssue({
+						code: z.ZodIssueCode.custom,
+						path: ['responses', index, 'answers', answerIndex, 'questionId'],
+						message: 'Answers must reference distinct questions',
+					})
+				}
+				seen.add(answer.questionId)
+			}
+		}
 		const responses = new Map<string, (typeof results.responses)[number]>()
 		for (const [index, response] of results.responses.entries()) {
 			if (responses.has(response.id)) {

package/src/ui/editor/ContentForm.tsx

@@ -27,6 +27,7 @@ import { Icon } from '../icons.js'
 import { uploadMediaAsset } from '../screens/media-upload.js'
 import { AiAssistPanel } from './AiAssistPanel.js'
 import { AUTOSAVE_DEBOUNCE_MS, shouldSnapshot } from './autosave.js'
+import { type BodyWarning, describeBodyWarnings, sortBodyWarnings } from './body-warnings.js'
 import {
 	buildContentCreatePayload,
 	buildContentUpdatePayload,
@@ -185,6 +186,12 @@ interface FormState {
 	lastSavedAt: number | null
 	/** Whether the AI assist panel is open. */
 	aiOpen: boolean
+	/**
+	 * Warn-severity body lint from the last save (#329). Previously the 200
+	 * payload was discarded, which is how a malformed Sources section reached a
+	 * published page — the server reported it and nothing showed the editor.
+	 */
+	bodyWarnings: BodyWarning[]
 }
 
 const EMPTY_CONTENT_METADATA_SELECTS: ContentMetadataSelectField[] = []
@@ -229,6 +236,7 @@ function createEmptyFormState(docId: string | null, metadata: ContentMetadata =
 		savedId: docId,
 		saving: false,
 		saveError: null,
+		bodyWarnings: [],
 		lastSavedAt: null,
 		aiOpen: false,
 	}
@@ -441,6 +449,17 @@ export function ContentForm({
 						return
 					}
 
+					// Carry warn-severity body lint into the editor. The server has
+					// reported these since #453; dropping the 200 payload here is what
+					// left them invisible.
+					const saved = (await res.json().catch(() => ({}))) as {
+						bodyWarnings?: BodyWarning[]
+					}
+					setForm((prev) => ({
+						...prev,
+						bodyWarnings: Array.isArray(saved.bodyWarnings) ? saved.bodyWarnings : [],
+					}))
+
 					// Snapshot cadence check
 					const now = Date.now()
 					savesSinceSnapshot.current += 1
@@ -1104,6 +1123,33 @@ export function ContentForm({
 				)}
 			</div>
 
+			{/* Body lint (#329). Shown beside the body editor so the correction is
+			    next to the text it applies to, rather than in a toast that is gone
+			    before the editor can act on it. */}
+			{form.bodyWarnings.length > 0 && (
+				<div style={bodyWarningPanel} role="status" aria-label="Body formatting warnings">
+					<div style={bodyWarningTitle}>
+						<Icon name="edit" size={12} style={{ color: 'var(--ink-faint)' }} />
+						<span>
+							{form.bodyWarnings.length}{' '}
+							{form.bodyWarnings.length === 1 ? 'formatting issue' : 'formatting issues'} — saved,
+							but these will block publishing
+						</span>
+					</div>
+					<ul style={bodyWarningList}>
+						{sortBodyWarnings(describeBodyWarnings(form.body, form.bodyWarnings)).map((warning) => (
+							<li key={`${warning.code}:${warning.line ?? 'x'}`} style={bodyWarningItem}>
+								<span style={bodyWarningLine}>
+									{warning.line === null ? 'Sources' : `Line ${warning.line}`}
+								</span>
+								<span>{warning.message}</span>
+								{warning.excerpt ? <code style={bodyWarningCode}>{warning.excerpt}</code> : null}
+							</li>
+						))}
+					</ul>
+				</div>
+			)}
+
 			{/* Footer: word count + read time (only for prose content) */}
 			{(contentType === 'article' || contentType === 'newsletter' || contentType === 'page') && (
 				<div style={footer}>
@@ -1680,6 +1726,53 @@ const dekInput: React.CSSProperties = {
 	resize: 'none',
 }
 
+const bodyWarningPanel: React.CSSProperties = {
+	marginTop: 16,
+	padding: '12px 14px',
+	borderRadius: 6,
+	border: '1px solid var(--border-soft)',
+	borderLeft: '3px solid var(--warn, #b8860b)',
+	background: 'var(--surface-sunken, rgba(0,0,0,0.02))',
+}
+
+const bodyWarningTitle: React.CSSProperties = {
+	display: 'flex',
+	alignItems: 'center',
+	gap: 8,
+	fontFamily: 'var(--mono)',
+	fontSize: 11.5,
+	color: 'var(--ink-muted)',
+	marginBottom: 8,
+}
+
+const bodyWarningList: React.CSSProperties = {
+	display: 'grid',
+	gap: 8,
+	margin: 0,
+	padding: 0,
+	listStyle: 'none',
+}
+
+const bodyWarningItem: React.CSSProperties = {
+	display: 'grid',
+	gap: 3,
+	fontSize: 13,
+	lineHeight: 1.45,
+}
+
+const bodyWarningLine: React.CSSProperties = {
+	fontFamily: 'var(--mono)',
+	fontSize: 11,
+	color: 'var(--ink-faint)',
+}
+
+const bodyWarningCode: React.CSSProperties = {
+	fontFamily: 'var(--mono)',
+	fontSize: 11.5,
+	color: 'var(--ink-muted)',
+	overflowWrap: 'anywhere',
+}
+
 const footer: React.CSSProperties = {
 	display: 'flex',
 	alignItems: 'center',

package/src/ui/editor/body-warnings.ts

@@ -0,0 +1,78 @@
+// Turn validator output into something an editor can act on (#329).
+//
+// The API returns `bodyWarnings` with character spans. An editor cannot use a
+// character offset — the design asks for "the affected line and a plain-language
+// correction" — so this maps each span onto a 1-based line number and the text
+// of that line.
+//
+// Pure on purpose: the mapping is the part worth testing, and keeping it out of
+// the component means it can be tested without rendering anything.
+
+export interface BodyWarning {
+	code: string
+	message: string
+	span?: { start: number; end: number }
+}
+
+export interface DescribedBodyWarning {
+	code: string
+	message: string
+	/** 1-based line number, or null when the warning carries no span. */
+	line: number | null
+	/** The offending line, trimmed. Null when there is no span to locate. */
+	excerpt: string | null
+}
+
+/** Longest excerpt shown inline before truncation. */
+const MAX_EXCERPT = 120
+
+function lineAt(markdown: string, offset: number): { line: number; text: string } | null {
+	if (offset < 0 || offset > markdown.length) return null
+	const before = markdown.slice(0, offset)
+	const line = before.split('\n').length
+	const lineStart = before.lastIndexOf('\n') + 1
+	const nextBreak = markdown.indexOf('\n', lineStart)
+	const text = markdown.slice(lineStart, nextBreak === -1 ? markdown.length : nextBreak)
+	return { line, text }
+}
+
+function truncate(value: string): string {
+	return value.length > MAX_EXCERPT ? `${value.slice(0, MAX_EXCERPT - 1)}…` : value
+}
+
+/**
+ * Attach a line number and excerpt to each warning.
+ *
+ * Warnings without a span keep `line: null` rather than being dropped or given
+ * a fabricated line 1 — a wrong line number sends an editor to the wrong place,
+ * which is worse than admitting the position is unknown.
+ */
+export function describeBodyWarnings(
+	markdown: string | null | undefined,
+	warnings: readonly BodyWarning[] | null | undefined,
+): DescribedBodyWarning[] {
+	if (!warnings || warnings.length === 0) return []
+	const source = markdown ?? ''
+
+	return warnings.map((warning) => {
+		const located = warning.span ? lineAt(source, warning.span.start) : null
+		return {
+			code: warning.code,
+			message: warning.message,
+			line: located ? located.line : null,
+			excerpt: located ? truncate(located.text.trim()) : null,
+		}
+	})
+}
+
+/** Stable ordering for display: by line, then by code. Unlocated ones last. */
+export function sortBodyWarnings(
+	warnings: readonly DescribedBodyWarning[],
+): DescribedBodyWarning[] {
+	return [...warnings].sort((a, b) => {
+		if (a.line === b.line) return a.code.localeCompare(b.code)
+		if (a.line === null) return 1
+		if (b.line === null) return -1
+		return a.line - b.line
+	})
+}