pi-roundtable 0.8.0 → 0.9.0

package/src/cli/line-diff.ts

@@ -0,0 +1,72 @@
+/** Every line of `before` and `after` in order: kept, removed, or added. */
+function lineOps(
+	before: readonly string[],
+	after: readonly string[],
+): { kind: " " | "-" | "+"; line: string }[] {
+	// The longest common subsequence, from the end, so the walk below reads forward.
+	const rows = before.length + 1;
+	const columns = after.length + 1;
+	const common = new Uint32Array(rows * columns);
+	for (let i = before.length - 1; i >= 0; i--)
+		for (let j = after.length - 1; j >= 0; j--)
+			common[i * columns + j] =
+				before[i] === after[j]
+					? (common[(i + 1) * columns + j + 1] ?? 0) + 1
+					: Math.max(
+							common[(i + 1) * columns + j] ?? 0,
+							common[i * columns + j + 1] ?? 0,
+						);
+	const ops: { kind: " " | "-" | "+"; line: string }[] = [];
+	let i = 0;
+	let j = 0;
+	while (i < before.length || j < after.length) {
+		if (i < before.length && j < after.length && before[i] === after[j]) {
+			ops.push({ kind: " ", line: before[i++] ?? "" });
+			j++;
+		} else if (
+			j < after.length &&
+			(i === before.length ||
+				(common[i * columns + j + 1] ?? 0) >
+					(common[(i + 1) * columns + j] ?? 0))
+		)
+			ops.push({ kind: "+", line: after[j++] ?? "" });
+		else ops.push({ kind: "-", line: before[i++] ?? "" });
+	}
+	return ops;
+}
+
+const CONTEXT = 3;
+
+/** The change from `before` to `after` as a unified diff with three lines of context; empty when they are the same. */
+export function lineDiff(
+	before: string,
+	after: string,
+	file: string,
+): string[] {
+	const ops = lineOps(before.split("\n"), after.split("\n"));
+	const changed = ops.flatMap((op, index) => (op.kind === " " ? [] : [index]));
+	if (changed.length === 0) return [];
+	// Changes closer than twice the context share a hunk.
+	const hunks: [number, number][] = [];
+	for (const index of changed) {
+		const last = hunks.at(-1);
+		if (last && index - last[1] <= 2 * CONTEXT) last[1] = index;
+		else hunks.push([index, index]);
+	}
+	const lines = [`--- ${file}`, `+++ ${file} (upgraded)`];
+	for (const [first, last] of hunks) {
+		const start = Math.max(0, first - CONTEXT);
+		const end = Math.min(ops.length - 1, last + CONTEXT);
+		const before = ops.slice(0, start);
+		const span = ops.slice(start, end + 1);
+		const count = (list: typeof ops, kind: "-" | "+") =>
+			list.filter((op) => op.kind !== (kind === "-" ? "+" : "-")).length;
+		const oldLength = count(span, "-");
+		const newLength = count(span, "+");
+		lines.push(
+			`@@ -${count(before, "-") + (oldLength > 0 ? 1 : 0)},${oldLength} +${count(before, "+") + (newLength > 0 ? 1 : 0)},${newLength} @@`,
+			...span.map((op) => `${op.kind}${op.line}`),
+		);
+	}
+	return lines;
+}

package/src/cli/principal.ts

@@ -0,0 +1,412 @@
+import type { SQL } from "bun";
+import { openPool } from "../core/db/migrations.ts";
+import { IdentityError } from "../core/domain/errors.ts";
+import type { AccessOwner } from "../core/identity/access-policy.ts";
+import { identityOf, parseIdentity } from "../core/identity/actor-facts.ts";
+import type { DeclaredIdentity } from "../core/identity/plugin-identities.ts";
+import {
+	type IdentityLink,
+	PgPrincipalStore,
+	type PrincipalRecord,
+	type Pronouns,
+	type RoleGrant,
+} from "../core/identity/principal-store.ts";
+import type { Tier } from "../core/speakers.ts";
+import { CONFIG_FILE } from "./project.ts";
+
+export const PRINCIPAL_USAGE = `  roundtable principal list    every principal, with its roles and its identities written as
+                                access in roundtable.config.ts takes them
+  roundtable principal show <principal>
+  roundtable principal create --name <name> [--pronouns he|she|they]
+  roundtable principal link <principal> <provider>:<subject>
+  roundtable principal unlink <provider>:<subject>
+  roundtable principal grant <principal> member|admin|owner
+  roundtable principal revoke <principal> member|admin|owner
+  roundtable principal disable <principal>
+  roundtable principal enable <principal>
+                                <principal> is a principal id, or an identity linked to it`;
+
+/** What every change prints: a running host reads its own copy for up to 30 seconds. */
+export const HOST_DELAY =
+	"A running host sees this within 30 seconds; a host that starts sees it at once.";
+
+const TIERS: readonly Tier[] = ["member", "admin", "owner"];
+const PRONOUNS: readonly Pronouns[] = ["he", "she", "they"];
+
+export interface PrincipalIo {
+	out(line: string): void;
+	err(line: string): void;
+}
+
+/** The owners the project's configuration names, or undefined when it does not load. */
+type ConfiguredOwners = readonly AccessOwner[] | undefined;
+
+/** The identities the project's plugins declare, or undefined when the configuration does not load. */
+export type ConfiguredIdentities = readonly DeclaredIdentity[] | undefined;
+
+/** What the project's configuration says, read by its schema alone. */
+export interface Configured {
+	owners: ConfiguredOwners;
+	identities: ConfiguredIdentities;
+}
+
+/** A refusal: the message is the whole answer, printed as it is. */
+class Refusal extends Error {}
+
+const describe = (principal: PrincipalRecord): string =>
+	`${principal.displayName}${principal.pronouns ? ` (${principal.pronouns})` : ""}`;
+
+const named = (principal: PrincipalRecord): string =>
+	`principal ${principal.id} (${principal.displayName})`;
+
+const stamp = (date: Date): string => date.toISOString();
+
+/**
+ * The principal a reference names: its id, or the principal an identity is linked to. A 0.8 id
+ * can be both, such as a web user's `oidc:…` id once that identity is linked to someone else;
+ * then it is refused rather than guessed.
+ */
+async function find(
+	store: PgPrincipalStore,
+	reference: string | undefined,
+): Promise<PrincipalRecord> {
+	if (reference === undefined) throw new Refusal("name a principal");
+	const byId = await store.get(reference);
+	const identity = parseIdentity(reference);
+	const link =
+		identity && (await store.identity(identity.provider, identity.subject));
+	const linked = link ? await store.get(link.principalId) : undefined;
+	if (byId && linked && byId.id !== linked.id)
+		throw new Refusal(
+			`${reference} names two principals: ${named(byId)} by its id, and ${named(linked)} by the identity linked to it. Name ${linked.id} by its id; to reach ${byId.id}, unlink ${reference} first, then link it to ${linked.id} again`,
+		);
+	const found = byId ?? linked;
+	if (found) return found;
+	throw new Refusal(
+		`there is no principal ${reference}, and no identity ${reference} is linked; roundtable principal list shows them`,
+	);
+}
+
+function identityArgument(text: string | undefined) {
+	const identity = text === undefined ? undefined : parseIdentity(text);
+	if (!identity)
+		throw new Refusal(
+			`expected an identity written <provider>:<subject>, such as discord:<user id>, got ${JSON.stringify(text ?? "")}`,
+		);
+	return identity;
+}
+
+function tierArgument(text: string | undefined): Tier {
+	if (!TIERS.includes(text as Tier))
+		throw new Refusal(
+			`expected a role, one of member, admin, or owner, got ${JSON.stringify(text ?? "")}`,
+		);
+	return text as Tier;
+}
+
+/** The plugin of the configuration that declares the identity; undefined when none does, unknown when the configuration does not load. */
+function declarer(
+	identities: ConfiguredIdentities,
+	link: IdentityLink,
+): string | undefined | "unknown" {
+	if (identities === undefined) return "unknown";
+	const text = identityOf(link);
+	return identities.find((declared) => declared.identity === text)?.plugin;
+}
+
+/** Where a link came from, and for a plugin's, which plugin declares it. */
+function sourceText(link: IdentityLink, configured: Configured): string {
+	if (link.source !== "plugin") return link.source;
+	const plugin = declarer(configured.identities, link);
+	if (plugin === "unknown") return "plugin";
+	return plugin === undefined
+		? "plugin, which no plugin declares any more: the next start unlinks it"
+		: `plugin ${plugin}`;
+}
+
+const linkLine = (link: IdentityLink, configured: Configured): string =>
+	`    ${identityOf(link)}  (${sourceText(link, configured)})`;
+
+const rolesText = (roles: readonly RoleGrant[]): string =>
+	roles.length === 0
+		? "none"
+		: roles.map((grant) => `${grant.role} (${grant.source})`).join(", ");
+
+/** Whether the person of its 0.8 id still links their own identity at first contact, as the identity service claims it. */
+const claimable = (
+	principal: PrincipalRecord,
+	roles: readonly RoleGrant[],
+): boolean =>
+	principal.claimable && !roles.some((grant) => grant.role === "owner");
+
+async function list(
+	store: PgPrincipalStore,
+	io: PrincipalIo,
+	configured: Configured,
+): Promise<void> {
+	const principals = await store.list();
+	for (const principal of principals) {
+		const roles = await store.rolesOf(principal.id);
+		io.out(
+			`${principal.id}  ${describe(principal)}${principal.disabled ? "  disabled" : ""}  roles: ${rolesText(roles)}`,
+		);
+		const links = await store.identitiesOf(principal.id);
+		for (const link of links) io.out(linkLine(link, configured));
+		if (links.length === 0)
+			io.out(
+				claimable(principal, roles)
+					? `    no identity linked yet; carried over from 0.8, so ${principal.id} links its own at its first contact`
+					: `    no identity linked yet; link one with roundtable principal link ${principal.id} <provider>:<subject>`,
+			);
+	}
+	io.out(
+		`${principals.length} ${principals.length === 1 ? "principal" : "principals"}. Each identity is written <provider>:<subject>, as access in roundtable.config.ts and roundtable principal link take it.`,
+	);
+}
+
+async function show(
+	store: PgPrincipalStore,
+	principal: PrincipalRecord,
+	io: PrincipalIo,
+	configured: Configured,
+): Promise<void> {
+	io.out(`principal ${principal.id}`);
+	io.out(`  name: ${describe(principal)}`);
+	io.out(`  status: ${principal.disabled ? "disabled" : "enabled"}`);
+	io.out(`  created: ${stamp(principal.createdAt)}`);
+	io.out(
+		`  last seen: ${principal.lastSeenAt ? `${stamp(principal.lastSeenAt)} as ${principal.lastTier ?? "unknown"}` : "never"}`,
+	);
+	io.out(`  roles: ${rolesText(await store.rolesOf(principal.id))}`);
+	const links = await store.identitiesOf(principal.id);
+	io.out(`  identities: ${links.length === 0 ? "none" : ""}`.trimEnd());
+	for (const link of links)
+		io.out(
+			`    ${identityOf(link)}  (${sourceText(link, configured)}, linked ${stamp(link.linkedAt)})`,
+		);
+}
+
+/** The value after `flag`, and the arguments without both. */
+function option(
+	args: readonly string[],
+	flag: string,
+): { value: string | undefined; rest: string[] } {
+	const at = args.indexOf(flag);
+	if (at === -1) return { value: undefined, rest: [...args] };
+	return { value: args[at + 1], rest: args.toSpliced(at, 2) };
+}
+
+/** Each subcommand and how many arguments it takes. */
+const ARITY: Record<string, number> = {
+	list: 0,
+	show: 1,
+	link: 2,
+	unlink: 1,
+	grant: 2,
+	revoke: 2,
+	disable: 1,
+	enable: 1,
+};
+
+/**
+ * Where the configuration lists an identity it linked: under the owner of the principal it is
+ * linked to (or an owner found by their identities), under another owner, nowhere any more, or
+ * unknown when the configuration does not load.
+ */
+function listedUnder(
+	owners: ConfiguredOwners,
+	link: IdentityLink,
+): "this principal" | "another owner" | "nowhere" | "unknown" {
+	if (owners === undefined) return "unknown";
+	const text = identityOf(link);
+	const holders = owners.filter((owner) =>
+		owner.identities.some((written) => {
+			const ref = parseIdentity(written);
+			return ref !== undefined && identityOf(ref) === text;
+		}),
+	);
+	if (holders.length === 0) return "nowhere";
+	return holders.some(
+		(owner) =>
+			owner.principal === undefined || owner.principal === link.principalId,
+	)
+		? "this principal"
+		: "another owner";
+}
+
+async function run(
+	store: PgPrincipalStore,
+	args: readonly string[],
+	io: PrincipalIo,
+	configured: Configured,
+): Promise<void> {
+	const { owners } = configured;
+	const [command, ...rest] = args;
+	if (command === "create") {
+		const name = option(rest, "--name");
+		const pronouns = option(name.rest, "--pronouns");
+		if (!name.value?.trim() || name.value.startsWith("--"))
+			throw new Refusal(
+				"create takes --name <name>, the name to address them by",
+			);
+		if (pronouns.rest.length > 0)
+			throw new Refusal(
+				`create takes --name and --pronouns, not ${pronouns.rest.join(" ")}`,
+			);
+		if (
+			pronouns.value !== undefined &&
+			!PRONOUNS.includes(pronouns.value as Pronouns)
+		)
+			throw new Refusal(
+				`--pronouns takes he, she, or they, not ${JSON.stringify(pronouns.value)}`,
+			);
+		const made = await store.create({
+			displayName: name.value.trim(),
+			...(pronouns.value ? { pronouns: pronouns.value as Pronouns } : {}),
+		});
+		io.out(
+			`Created ${named(made)}. Link an identity to it with roundtable principal link ${made.id} <provider>:<subject>.`,
+		);
+		io.out(HOST_DELAY);
+		return;
+	}
+	const arity = command === undefined ? undefined : ARITY[command];
+	if (arity === undefined)
+		throw new Refusal(`unknown principal command. Usage:\n${PRINCIPAL_USAGE}`);
+	if (arity !== rest.length)
+		throw new Refusal(
+			`${command} takes ${arity} ${arity === 1 ? "argument" : "arguments"}. Usage:\n${PRINCIPAL_USAGE}`,
+		);
+	if (command === "list") return list(store, io, configured);
+	if (command === "unlink") {
+		const identity = identityArgument(rest[0]);
+		const link = await store.identity(identity.provider, identity.subject);
+		// A plugin's identity is linked again by the next start while the plugin declares it.
+		const plugin =
+			link?.source === "plugin"
+				? declarer(configured.identities, link)
+				: undefined;
+		if (link && plugin === "unknown")
+			throw new Refusal(
+				`${identityOf(identity)} is linked to principal ${link.principalId} as an identity a plugin declares, and ${CONFIG_FILE} does not load here to say whether a plugin still declares it; fix it, then try again`,
+			);
+		if (link && plugin !== undefined)
+			throw new Refusal(
+				`${identityOf(identity)} is linked to principal ${link.principalId} as an identity plugin ${plugin} declares; change that plugin's options in ${CONFIG_FILE} instead, and the next start moves or unlinks it`,
+			);
+		// Whoever linked it (the configuration, a first contact, the CLI, or a 0.8 claim), an identity
+		// an owner is listed by would be admitted by a running host as someone new once unlinked here,
+		// and the next start would fail on it.
+		const listed = link ? listedUnder(owners, link) : "nowhere";
+		if (link && (listed === "this principal" || listed === "unknown"))
+			throw new Refusal(
+				`${identityOf(identity)} is linked to principal ${link.principalId}, ${listed === "unknown" ? `and ${CONFIG_FILE} does not load here to say whether it lists it under an owner; fix it, or` : "which the configuration lists under an owner;"} remove it from access.owners[*].identities in ${CONFIG_FILE} instead, ${link.source === "config" ? "and the next start unlinks it" : "then unlink it here once the host has started with that configuration"}`,
+			);
+		if (!link || !(await store.unlink(identity.provider, identity.subject)))
+			throw new Refusal(
+				`${identityOf(identity)} is not linked to any principal`,
+			);
+		io.out(
+			`Unlinked ${identityOf(identity)} from principal ${link.principalId}.`,
+		);
+		if (listed === "another owner")
+			io.out(
+				"The configuration lists it under another owner, which a running host does not read: stop the host, then start it with this configuration. If a new p_… principal appears with this identity before then, unlink it again.",
+			);
+		io.out(HOST_DELAY);
+		return;
+	}
+	const principal = await find(store, rest[0]);
+	if (command === "show") return show(store, principal, io, configured);
+	if (command === "link") {
+		const identity = identityArgument(rest[1]);
+		const spends = claimable(principal, await store.rolesOf(principal.id));
+		await store.link(principal.id, identity, "cli");
+		io.out(`Linked ${identityOf(identity)} to ${named(principal)}.`);
+		if (spends)
+			io.out(
+				`This uses up the 0.8 claim of principal ${principal.id}: its 0.8 id no longer links its own identity at first contact, even once this one is unlinked. Link each of their other identities here.`,
+			);
+	} else if (command === "grant") {
+		const role = tierArgument(rest[1]);
+		// Granting it again would make it the CLI's, outliving its removal from the configuration.
+		const held = (await store.rolesOf(principal.id)).find(
+			(grant) => grant.role === role,
+		);
+		if (held?.source === "config") {
+			io.out(
+				`${named(principal)} already holds ${role}, granted by the configuration; nothing changed.`,
+			);
+			return;
+		}
+		await store.grant(principal.id, role, "cli");
+		io.out(`Granted ${role} to ${named(principal)}.`);
+		if (role === "owner")
+			io.out(
+				"The owner role is granted only here and in the configuration; no role a surface reports makes an owner.",
+			);
+	} else if (command === "revoke") {
+		const role = tierArgument(rest[1]);
+		const grant = (await store.rolesOf(principal.id)).find(
+			(held) => held.role === role,
+		);
+		if (!grant)
+			throw new Refusal(`principal ${principal.id} does not hold ${role}`);
+		if (grant.source === "config")
+			throw new Refusal(
+				`principal ${principal.id} holds ${role} from the configuration, which grants it again at every start; remove them from access.owners in roundtable.config.ts instead`,
+			);
+		await store.revoke(principal.id, role, "cli");
+		io.out(`Revoked ${role} from ${named(principal)}.`);
+	} else if (command === "disable") {
+		await store.disable(principal.id);
+		io.out(
+			`Disabled ${named(principal)}: no surface serves them, and their background turns are skipped.`,
+		);
+	} else {
+		await store.enable(principal.id);
+		io.out(`Enabled ${named(principal)}.`);
+	}
+	io.out(HOST_DELAY);
+}
+
+/** Whether the host has made the principal tables, which its first start on 0.9 does. */
+async function hasTables(sql: SQL): Promise<boolean> {
+	const [row] = await sql`
+		SELECT to_regclass('principals') IS NOT NULL
+			AND to_regclass('principal_identities') IS NOT NULL
+			AND to_regclass('principal_roles') IS NOT NULL AS made`;
+	return row?.made === true;
+}
+
+/**
+ * Runs one `roundtable principal` command on the database at `url`, beside a host that may be
+ * running, and returns the exit code. It changes the database directly; a running host's cache
+ * catches up within 30 seconds, which every change says.
+ */
+export async function principalCommand(
+	url: string,
+	args: readonly string[],
+	io: PrincipalIo,
+	configured: Configured,
+): Promise<number> {
+	const sql = openPool(url);
+	try {
+		if (!(await hasTables(sql))) {
+			io.err(
+				"This database has no principals yet: start the host on pi-roundtable 0.9 once, and its migrations make them from the people it already knows.",
+			);
+			return 1;
+		}
+		await run(await PgPrincipalStore.attach(sql), args, io, configured);
+		return 0;
+	} catch (error) {
+		if (error instanceof Refusal || error instanceof IdentityError) {
+			io.err(error.message);
+			return 1;
+		}
+		throw error;
+	} finally {
+		await sql.close();
+	}
+}

package/src/cli/project.ts

@@ -32,6 +32,11 @@ export async function loadConfigFile(cwd: string): Promise<unknown> {
 		throw new Error(
 			`${CONFIG_FILE} is not in ${cwd}. Run this in the project directory, or create a project with \`roundtable init\`.`,
 		);
+	return loadDefault(path);
+}
+
+/** The value a configuration file exports by default, imported with Bun. */
+export async function loadDefault(path: string): Promise<unknown> {
 	const module = (await import(pathToFileURL(path).href)) as {
 		default?: unknown;
 	};

package/src/cli/report.ts

@@ -1,6 +1,10 @@
-/** How one check ended: passed, failed with what to do, or not run because it needs something an earlier check reports. */
+/**
+ * How one check ended: passed, passed with a warning and what to do about it, failed with what to
+ * do, or not run because it needs something an earlier check reports. A warning fails nothing.
+ */
 export type Result =
 	| { status: "ok"; detail?: string }
+	| { status: "warn"; problem: string; fix: string }
 	| { status: "fail"; problem: string; fix: string }
 	| { status: "skipped"; reason: string };
 
@@ -23,6 +27,11 @@ export const fail = (problem: string, fix: string): Result => ({
 	problem,
 	fix,
 });
+export const warn = (problem: string, fix: string): Result => ({
+	status: "warn",
+	problem,
+	fix,
+});
 export const skipped = (reason: string): Result => ({
 	status: "skipped",
 	reason,
@@ -53,7 +62,7 @@ export async function runChecks(checks: readonly Check[]): Promise<Outcome[]> {
 export const failed = (outcomes: readonly Outcome[]): Outcome[] =>
 	outcomes.filter(({ result }) => result.status === "fail");
 
-/** One line per check, and for a failure its problem and fix underneath. */
+/** One line per check, and for a warning or a failure its problem and fix underneath. */
 export function formatOutcomes(outcomes: readonly Outcome[]): string[] {
 	return outcomes.flatMap(({ name, result }) => {
 		if (result.status === "ok")
@@ -61,7 +70,7 @@ export function formatOutcomes(outcomes: readonly Outcome[]): string[] {
 		if (result.status === "skipped")
 			return [`- ${name}: skipped, ${result.reason}`];
 		return [
-			`✗ ${name}: ${result.problem}`,
+			`${result.status === "warn" ? "!" : "✗"} ${name}: ${result.problem}`,
 			...result.fix.split("\n").map((line) => `    ${line}`),
 		];
 	});

package/src/cli/upgrade-rewrite.ts

@@ -0,0 +1,102 @@
+import { ConfigEditError, type Node } from "./config-edit.ts";
+
+/** One replacement of the source text: [start, end) becomes `text`. */
+export interface Edit {
+	start: number;
+	end: number;
+	text: string;
+}
+
+/**
+ * Rewrites one configuration's text. Each place it cannot read with confidence, such as an owner
+ * built elsewhere or spread into the object, is a ConfigEditError naming the file, line, and column.
+ */
+export class Rewrite {
+	readonly source: string;
+	readonly #file: string;
+	readonly #comments: readonly Node[];
+	readonly edits: Edit[] = [];
+	readonly moved: Node[] = [];
+
+	constructor(source: string, file: string, comments: readonly Node[]) {
+		this.source = source;
+		this.#file = file;
+		this.#comments = comments;
+	}
+
+	text(node: Node): string {
+		return this.source.slice(node.start, node.end);
+	}
+
+	/** A ConfigEditError at the node, as `file:line:column: message`. */
+	at(node: Node, message: string): ConfigEditError {
+		const before = this.source.slice(0, node.start);
+		const line = before.split("\n").length;
+		const column = node.start - (before.lastIndexOf("\n") + 1) + 1;
+		return new ConfigEditError(`${this.#file}:${line}:${column}: ${message}`);
+	}
+
+	/** The indentation of the node's line, when the node starts it; undefined when it shares the line. */
+	indentOf(node: Node): string | undefined {
+		const lineStart = this.source.lastIndexOf("\n", node.start - 1) + 1;
+		const before = this.source.slice(lineStart, node.start);
+		return /^[ \t]*$/.test(before) ? before : undefined;
+	}
+
+	/** The comments inside [start, end). */
+	commentsIn(start: number, end: number): Node[] {
+		return this.#comments.filter(
+			(comment) => comment.start >= start && comment.end <= end,
+		);
+	}
+
+	/**
+	 * Where the property and what belongs to it end when it is removed: the comment lines right
+	 * above it, its comma, and a comment after it on its line, through the line's end when it has
+	 * the line to itself.
+	 */
+	removal(property: Node): { start: number; end: number } {
+		const source = this.source;
+		let end = property.end;
+		const after = /^[ \t]*,?[ \t]*(\/\/[^\n]*|\/\*[^\n]*?\*\/)?[ \t]*/.exec(
+			source.slice(end),
+		);
+		end += after?.[0].length ?? 0;
+		const indent = this.indentOf(property);
+		if (indent === undefined || (source[end] !== "\n" && end < source.length))
+			return { start: property.start, end };
+		let start = property.start - indent.length;
+		for (;;) {
+			const previousEnd = start - 1;
+			if (previousEnd < 0) break;
+			const previousStart = source.lastIndexOf("\n", previousEnd - 1) + 1;
+			const line = source.slice(previousStart, previousEnd).trim();
+			if (
+				!(
+					line.startsWith("//") ||
+					(line.startsWith("/*") && line.endsWith("*/"))
+				)
+			)
+				break;
+			start = previousStart;
+		}
+		return { start, end: end + (source[end] === "\n" ? 1 : 0) };
+	}
+
+	/** The comment lines to put back above a rewritten property, at its indentation. */
+	commentLines(comments: readonly Node[], indent: string | undefined): string {
+		if (comments.length === 0) return "";
+		if (indent === undefined) {
+			const line = comments.find((comment) => comment.type === "CommentLine");
+			if (line)
+				throw this.at(
+					line,
+					"this comment is inside what the upgrade rewrites, on a line it shares with other keys; move it out, or rewrite the key by hand",
+				);
+			return `${comments.map((comment) => this.text(comment)).join(" ")} `;
+		}
+		return comments
+			.map((comment) => `${this.text(comment)}\n${indent}`)
+			.join("");
+	}
+}