expo-release 2.3.1 → 2.4.0

package/src/decide.ts

@@ -7,11 +7,15 @@ import { appendGitHubOutput } from './github-output'
 import {
 	type CommandRunner,
 	easCommand,
-	getRecord,
 	generateFingerprint,
+	getRecord,
 	parseJson,
-	runCaptured
+	parseJsonDocument,
+	runCaptured,
+	StageError,
+	stage
 } from './run'
+import { expoCommand } from './source-maps'
 
 export type EASBuildStatus =
 	| 'finished'
@@ -28,14 +32,33 @@ export type EASBuild = {
 	buildUrl?: string
 	fingerprint?: string
 	runtimeVersion?: string
+	/** Why EAS failed the build, for an errored one. */
+	error?: string
+}
+
+/** Why the decision came out the way it did. */
+export type DecisionReason =
+	| 'no-impact-path'
+	| 'finished-build'
+	| 'build-in-progress'
+	| 'no-build-for-fingerprint'
+
+/** What changed since the profile's last finished build, for a native decision. */
+export type FingerprintDiff = {
+	buildId: string
+	buildUrl?: string
+	/** `changed <path>`, `added <path>` or `removed <path>`; contents sources by id. */
+	sources: string[]
 }
 
 export type ReleaseDecision = {
 	deployType: DeployType
+	reason: DecisionReason
 	nativeBuildPending: boolean
 	changedFiles: string[]
 	fingerprint: string | null
 	build: EASBuild | null
+	fingerprintDiff?: FingerprintDiff | null
 }
 
 export type DecisionInput = {
@@ -45,6 +68,10 @@ export type DecisionInput = {
 	platform: ReleasePlatform
 	impactPaths: string[]
 	ignoreExpoImpact?: boolean
+	/** Passed to `eas fingerprint:compare` when explaining a native decision. */
+	environment?: string
+	/** Runs once the diff says EAS is needed, before the first EAS command. */
+	preflight?: () => Promise<void>
 }
 
 const ACTIVE_BUILD_STATUSES: readonly EASBuildStatus[] = [
@@ -88,11 +115,18 @@ function normalizeBuildStatus(value: string): EASBuildStatus | null {
 	return null
 }
 
+// eas-cli prints its GraphQL BuildFragment: `project.ownerAccount.name`,
+// `project.slug` and a top-level `runtimeVersion`. `app` and `runtime` are kept
+// as fallbacks for older output.
 function dashboardBuildUrl(
 	record: Record<string, unknown>
 ): string | undefined {
-	const ownerName = nestedString(record, 'app', 'ownerAccount', 'name')
-	const slug = nestedString(record, 'app', 'slug')
+	const ownerName =
+		nestedString(record, 'project', 'ownerAccount', 'name') ??
+		nestedString(record, 'app', 'ownerAccount', 'name')
+	const slug =
+		nestedString(record, 'project', 'slug') ??
+		nestedString(record, 'app', 'slug')
 	if (typeof record.id !== 'string' || !ownerName || !slug) {
 		return undefined
 	}
@@ -122,14 +156,20 @@ export function parseBuildList(output: string): EASBuild[] {
 
 		const buildUrl = dashboardBuildUrl(record)
 		const fingerprint = nestedString(record, 'fingerprint', 'hash')
-		const runtimeVersion = nestedString(record, 'runtime', 'version')
+		const runtimeVersion =
+			nestedString(record, 'runtimeVersion') ??
+			nestedString(record, 'runtime', 'version')
+		const errorCode = nestedString(record, 'error', 'errorCode')
+		const errorMessage = nestedString(record, 'error', 'message')
+		const error = [errorCode, errorMessage].filter(Boolean).join(': ')
 
 		builds.push({
 			id: record.id,
 			status,
 			...(buildUrl ? { buildUrl } : {}),
 			...(fingerprint ? { fingerprint } : {}),
-			...(runtimeVersion ? { runtimeVersion } : {})
+			...(runtimeVersion ? { runtimeVersion } : {}),
+			...(error ? { error } : {})
 		})
 	}
 
@@ -159,12 +199,18 @@ export function hasExpoImpact(
 
 export function resolveBuildDecision(builds: EASBuild[]): {
 	deployType: Exclude<DeployType, 'none'>
+	reason: Exclude<DecisionReason, 'no-impact-path'>
 	nativeBuildPending: boolean
 	build: EASBuild | null
 } {
 	const finished = builds.find((build) => build.status === 'finished')
 	if (finished) {
-		return { deployType: 'ota', nativeBuildPending: false, build: finished }
+		return {
+			deployType: 'ota',
+			reason: 'finished-build',
+			nativeBuildPending: false,
+			build: finished
+		}
 	}
 
 	const inProgress = builds.find((build) =>
@@ -173,6 +219,7 @@ export function resolveBuildDecision(builds: EASBuild[]): {
 	if (inProgress) {
 		return {
 			deployType: 'ota',
+			reason: 'build-in-progress',
 			nativeBuildPending: true,
 			build: inProgress
 		}
@@ -180,13 +227,59 @@ export function resolveBuildDecision(builds: EASBuild[]): {
 
 	const newest = builds[0]
 	if (newest?.status === 'errored') {
-		const location = newest.buildUrl ?? newest.id
-		throw new Error(
-			`The most recent native build for this fingerprint failed (${location}). Fix the failure or use --operation force-native to queue another build.`
-		)
+		const lines = [
+			`The newest native build for this fingerprint failed on EAS${newest.error ? `: ${newest.error}` : ` (build ${newest.id})`}`,
+			newest.buildUrl,
+			'Fix it, then run the workflow with operation force-native.'
+		].filter((line): line is string => Boolean(line))
+		throw new StageError('errored build', lines.join('\n'), lines)
 	}
 
-	return { deployType: 'native', nativeBuildPending: false, build: null }
+	return {
+		deployType: 'native',
+		reason: 'no-build-for-fingerprint',
+		nativeBuildPending: false,
+		build: null
+	}
+}
+
+async function readPullRequestBase(): Promise<string | undefined> {
+	const path = process.env.GITHUB_EVENT_PATH
+	if (!path) return undefined
+	try {
+		const event = (await Bun.file(path).json()) as {
+			pull_request?: { base?: { sha?: unknown } }
+		}
+		const sha = event.pull_request?.base?.sha
+		return typeof sha === 'string' && sha ? sha : undefined
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * Without `--base`: the merge base with the PR's base branch on a pull request
+ * (`github.event.before` there is the previous push, not the base), else
+ * `github.event.before`.
+ */
+export async function defaultBase(
+	head: string | undefined,
+	commandRunner: CommandRunner
+): Promise<string | undefined> {
+	const event = process.env.GITHUB_EVENT_NAME
+	if (event === 'pull_request' || event === 'pull_request_target') {
+		const base = await readPullRequestBase()
+		if (base && head) {
+			try {
+				const mergeBase = (
+					await commandRunner(['git', 'merge-base', base, head])
+				).trim()
+				if (mergeBase) return mergeBase
+			} catch {}
+		}
+		if (base) return base
+	}
+	return process.env.GITHUB_EVENT_BEFORE?.trim() || undefined
 }
 
 async function getChangedFiles(
@@ -194,7 +287,8 @@ async function getChangedFiles(
 	commandRunner: CommandRunner
 ): Promise<{ files: string[]; unreachable: boolean }> {
 	const head = input.head
-	if (!input.base || !head || /^0+$/.test(input.base)) {
+	const base = input.base ?? (await defaultBase(head, commandRunner))
+	if (!base || !head || /^0+$/.test(base)) {
 		return { files: [], unreachable: true }
 	}
 
@@ -205,7 +299,7 @@ async function getChangedFiles(
 			'diff.relative=false',
 			'diff',
 			'--name-only',
-			input.base,
+			base,
 			head
 		])
 		return {
@@ -244,13 +338,116 @@ async function getMatchingBuilds(
 	)
 }
 
+type FingerprintSource = {
+	type?: unknown
+	filePath?: unknown
+	id?: unknown
+	hash?: unknown
+}
+
+function fingerprintSources(value: unknown): Map<string, unknown> {
+	const sources = (value as { sources?: unknown } | null)?.sources
+	const map = new Map<string, unknown>()
+	if (!Array.isArray(sources)) return map
+	for (const source of sources as FingerprintSource[]) {
+		const key =
+			source.type === 'contents' ? source.id : (source.filePath ?? source.id)
+		if (typeof key === 'string') map.set(key, source.hash ?? null)
+	}
+	return map
+}
+
+const MAX_DIFF_SOURCES = 30
+
+/** Changed sources between the two fingerprints `eas fingerprint:compare --json` prints. */
+export function diffFingerprintSources(compare: unknown): string[] {
+	const record = getRecord(compare, 'EAS fingerprint:compare')
+	const before = fingerprintSources(record.fingerprint1)
+	const after = fingerprintSources(record.fingerprint2)
+	const lines: string[] = []
+	for (const [key, hash] of after) {
+		if (!before.has(key)) lines.push(`added ${key}`)
+		else if (before.get(key) !== hash) lines.push(`changed ${key}`)
+	}
+	for (const key of before.keys()) {
+		if (!after.has(key)) lines.push(`removed ${key}`)
+	}
+	if (lines.length <= MAX_DIFF_SOURCES) return lines
+	return [
+		...lines.slice(0, MAX_DIFF_SOURCES),
+		`... and ${lines.length - MAX_DIFF_SOURCES} more`
+	]
+}
+
+/**
+ * Compares the current fingerprint with the profile's last finished build.
+ * Two extra EAS calls, made only for a native decision. A failure here only
+ * loses the explanation, never the release.
+ */
+async function explainNativeDecision(
+	input: DecisionInput,
+	commandRunner: CommandRunner
+): Promise<FingerprintDiff | null> {
+	try {
+		return await stage('fingerprint diff', async () => {
+			const [last] = parseBuildList(
+				await commandRunner(
+					easCommand(
+						'build:list',
+						'--platform',
+						input.platform,
+						'--build-profile',
+						input.profile,
+						'--status',
+						'finished',
+						'--limit',
+						'1',
+						'--json',
+						'--non-interactive'
+					)
+				)
+			)
+			if (!last) return null
+			const command = easCommand(
+				'fingerprint:compare',
+				'--build-id',
+				last.id,
+				'--json',
+				'--non-interactive'
+			)
+			if (input.environment) command.push('--environment', input.environment)
+			const { value } = parseJsonDocument(await commandRunner(command))
+			return {
+				buildId: last.id,
+				...(last.buildUrl ? { buildUrl: last.buildUrl } : {}),
+				sources: diffFingerprintSources(value)
+			}
+		})
+	} catch (error) {
+		process.stderr.write(
+			`Warning: could not compare the fingerprint with the last finished build: ${error instanceof Error ? error.message : String(error)}\n`
+		)
+		return null
+	}
+}
+
+async function explainConfigFailure(
+	commandRunner: CommandRunner
+): Promise<string> {
+	try {
+		await commandRunner(expoCommand('config', '--json'))
+		return ''
+	} catch (error) {
+		return error instanceof Error ? error.message : String(error)
+	}
+}
+
 export async function decideRelease(
 	input: DecisionInput,
 	commandRunner: CommandRunner = runCaptured
 ): Promise<ReleaseDecision> {
-	const { files: changedFiles, unreachable } = await getChangedFiles(
-		input,
-		commandRunner
+	const { files: changedFiles, unreachable } = await stage('diff', () =>
+		getChangedFiles(input, commandRunner)
 	)
 
 	if (
@@ -260,6 +457,7 @@ export async function decideRelease(
 	) {
 		return {
 			deployType: 'none',
+			reason: 'no-impact-path',
 			nativeBuildPending: false,
 			changedFiles,
 			fingerprint: null,
@@ -267,17 +465,27 @@ export async function decideRelease(
 		}
 	}
 
-	const fingerprint = await generateFingerprint(input, commandRunner)
-	const resolved = resolveBuildDecision(
-		await getMatchingBuilds(input, fingerprint, commandRunner)
+	await input.preflight?.()
+	const fingerprint = await stage('fingerprint', () =>
+		generateFingerprint(input, commandRunner, () =>
+			explainConfigFailure(commandRunner)
+		)
+	)
+	const builds = await stage('build list', () =>
+		getMatchingBuilds(input, fingerprint, commandRunner)
 	)
+	const resolved = resolveBuildDecision(builds)
 
 	return {
 		deployType: resolved.deployType,
+		reason: resolved.reason,
 		nativeBuildPending: resolved.nativeBuildPending,
 		changedFiles,
 		fingerprint,
-		build: resolved.build
+		build: resolved.build,
+		...(resolved.deployType === 'native'
+			? { fingerprintDiff: await explainNativeDecision(input, commandRunner) }
+			: {})
 	}
 }
 
@@ -288,6 +496,12 @@ export async function writeDecideGitHubOutput(decision: ReleaseDecision) {
 		changed: String(decision.deployType !== 'none'),
 		fingerprint: decision.fingerprint ?? '',
 		build_id: decision.build?.id ?? '',
-		build_url: decision.build?.buildUrl ?? ''
+		build_url: decision.build?.buildUrl ?? '',
+		reason: decision.reason,
+		changed_sources: decision.fingerprintDiff?.sources.join('\n') ?? '',
+		compared_build_url:
+			decision.fingerprintDiff?.buildUrl ??
+			decision.fingerprintDiff?.buildId ??
+			''
 	})
 }

package/src/doctor.ts

@@ -0,0 +1,296 @@
+import type { ReleasePlatform } from './args'
+import type { BuildProfile, EasJson } from './eas-json'
+import { readExpoSdkMajor } from './operate'
+import { type CommandRunner, easCommand, runSilent } from './run'
+import { expoCommand } from './source-maps'
+
+export type Finding = {
+	level: 'error' | 'warning'
+	message: string
+	/** The command or change that fixes it. */
+	fix?: string
+}
+
+export type DoctorInput = {
+	profile: string
+	platform: ReleasePlatform
+	environment?: string
+	autoSubmit: boolean
+	easJson: EasJson | null
+	buildProfile: BuildProfile | null
+	/** Also load the app config (`expo config`, slow in large apps). */
+	full?: boolean
+	readPackageJson?: () => Promise<unknown>
+	readFile?: (path: string) => Promise<string | null>
+	env?: Record<string, string | undefined>
+	bunVersion?: string
+}
+
+const CREDENTIAL_FILE = /\.(keystore|jks|p8|p12|mobileprovision)$/
+
+async function tryRun(runner: CommandRunner, command: string[]) {
+	try {
+		return { ok: true as const, output: await runner(command) }
+	} catch (error) {
+		return {
+			ok: false as const,
+			error: error instanceof Error ? error.message : String(error)
+		}
+	}
+}
+
+async function defaultReadFile(path: string): Promise<string | null> {
+	const file = Bun.file(path)
+	return (await file.exists()) ? file.text() : null
+}
+
+function versionOf(output: string): string | undefined {
+	return output.match(/(\d+\.\d+\.\d+)/)?.[1]
+}
+
+async function checkTools(
+	input: DoctorInput,
+	runner: CommandRunner,
+	findings: Finding[]
+) {
+	const env = input.env ?? process.env
+	const eas = await tryRun(runner, easCommand('--version'))
+	if (!eas.ok) {
+		findings.push({
+			level: 'error',
+			message: 'eas-cli did not run.',
+			fix: 'Add eas-cli to the app devDependencies, or set it up with expo/expo-github-action.'
+		})
+	} else {
+		const wanted = input.easJson?.cli?.version
+		const actual = versionOf(eas.output)
+		if (wanted && actual && !Bun.semver.satisfies(actual, wanted)) {
+			findings.push({
+				level: 'error',
+				message: `eas-cli ${actual} does not satisfy eas.json cli.version ${wanted}.`,
+				fix: `Pin eas-cli ${wanted} in the app devDependencies or the workflow.`
+			})
+		}
+	}
+	if (env.CI && !env.EXPO_TOKEN) {
+		findings.push({
+			level: 'error',
+			message: 'EXPO_TOKEN is not set.',
+			fix: 'Add the EXPO_TOKEN secret (https://expo.dev/settings/access-tokens) and pass it to the job.'
+		})
+	}
+
+	const bun = input.buildProfile?.bun
+	const bunVersion = input.bunVersion ?? Bun.version
+	if (bun && bun !== bunVersion) {
+		findings.push({
+			level: 'error',
+			message: `This job runs Bun ${bunVersion}, the "${input.profile}" profile builds with Bun ${bun}. The fingerprint and lockfile can differ between them.`,
+			fix: `Use Bun ${bun} in CI, or set build.${input.profile}.bun to ${bunVersion}.`
+		})
+	}
+	const node = input.buildProfile?.node
+	if (node) {
+		const actual = await tryRun(runner, ['node', '--version'])
+		const version = actual.ok ? versionOf(actual.output) : undefined
+		if (version && version !== node) {
+			findings.push({
+				level: 'warning',
+				message: `This job runs Node ${version}, the "${input.profile}" profile builds with Node ${node}.`,
+				fix: `Use Node ${node} in CI (actions/setup-node).`
+			})
+		}
+	}
+}
+
+async function checkProfile(input: DoctorInput, findings: Finding[]) {
+	if (!input.easJson) {
+		findings.push({
+			level: 'error',
+			message: 'No eas.json in the working directory.',
+			fix: 'Set working-directory to the Expo app, or run `eas build:configure` there.'
+		})
+		return
+	}
+	if (!input.buildProfile) {
+		const names = Object.keys(input.easJson.build ?? {}).join(', ') || 'none'
+		findings.push({
+			level: 'error',
+			message: `eas.json has no build profile "${input.profile}" (profiles: ${names}).`
+		})
+		return
+	}
+	if (!input.buildProfile.channel) {
+		findings.push({
+			level: 'warning',
+			message: `Build profile "${input.profile}" has no channel, so its builds receive no EAS updates.`,
+			fix: `Set build.${input.profile}.channel in eas.json.`
+		})
+	}
+	if (input.autoSubmit && !input.easJson.submit?.[input.profile]) {
+		findings.push({
+			level: 'warning',
+			message: `auto-submit is on, but eas.json has no submit.${input.profile}.`,
+			fix:
+				input.platform === 'ios'
+					? `Set submit.${input.profile}.ios.ascAppId.`
+					: `Set submit.${input.profile}.android.serviceAccountKeyPath, pointing at a file from an EAS file secret.`
+		})
+	}
+	if (!input.environment) {
+		const major = await readExpoSdkMajor(input.readPackageJson)
+		if (major !== null && major >= 55) {
+			findings.push({
+				level: 'error',
+				message: 'Expo SDK 55+ needs an EAS environment for eas update.',
+				fix: `Set build.${input.profile}.environment in eas.json, or pass --environment.`
+			})
+		}
+	}
+}
+
+async function checkTrackedFiles(
+	runner: CommandRunner,
+	findings: Finding[],
+	readFile: (path: string) => Promise<string | null>
+) {
+	const listed = await tryRun(runner, ['git', 'ls-files'])
+	if (!listed.ok) return
+	const files = listed.output.split('\n').filter(Boolean)
+
+	const credentials = files.filter(
+		(file) => CREDENTIAL_FILE.test(file) && !/(^|\/)debug\.keystore$/.test(file)
+	)
+	for (const file of files) {
+		if (!file.endsWith('.json') || credentials.includes(file)) continue
+		const text = await readFile(file)
+		if (
+			text &&
+			text.length < 50_000 &&
+			/"type"\s*:\s*"service_account"/.test(text)
+		) {
+			credentials.push(file)
+		}
+	}
+	if (credentials.length > 0) {
+		findings.push({
+			level: 'error',
+			message: `Credentials are committed: ${credentials.join(', ')}.`,
+			fix: 'Remove them from git, rotate them, and keep them in EAS (`eas credentials`, EAS file secrets).'
+		})
+	}
+
+	const generated = files.filter(
+		(file) => /^\.expo\//.test(file) || /\.log$/.test(file)
+	)
+	if (generated.length > 0) {
+		findings.push({
+			level: 'warning',
+			message: `Generated files are committed: ${generated.slice(0, 5).join(', ')}${generated.length > 5 ? `, and ${generated.length - 5} more` : ''}.`,
+			fix: 'git rm --cached them and add .expo/ and *.log to .gitignore.'
+		})
+	}
+
+	const nativeDirs = ['android', 'ios'].filter((dir) =>
+		files.some((file) => file.startsWith(`${dir}/`))
+	)
+	if (nativeDirs.length === 0) return
+	const ignore = (await readFile('.fingerprintignore')) ?? ''
+	// Only a pattern for the whole folder hides it; `android/build/**` and the
+	// like are ordinary ignores.
+	const lines = ignore.split('\n').map((line) => line.trim().replace(/^\//, ''))
+	const hidden = nativeDirs.filter((dir) =>
+		lines.some((line) =>
+			[dir, `${dir}/`, `${dir}/*`, `${dir}/**`, `${dir}/**/*`].includes(line)
+		)
+	)
+	if (hidden.length > 0) {
+		findings.push({
+			level: 'error',
+			message: `${hidden.join(' and ')} are committed, and .fingerprintignore hides them: EAS builds the committed tree, but a change there never asks for a native build.`,
+			fix: 'Either delete and gitignore the native folders (continuous native generation), or stop ignoring them in .fingerprintignore.'
+		})
+	}
+	return nativeDirs
+}
+
+async function checkAppConfig(
+	runner: CommandRunner,
+	findings: Finding[],
+	nativeDirs: string[]
+) {
+	const config = await tryRun(runner, expoCommand('config', '--json'))
+	if (!config.ok) {
+		findings.push({
+			level: 'error',
+			message: `The app config did not load:\n${config.error}`,
+			fix: 'Run `npx expo config` in the app with the same environment variables.'
+		})
+		return
+	}
+	let parsed: { runtimeVersion?: unknown; plugins?: unknown } = {}
+	try {
+		parsed = JSON.parse(config.output)
+	} catch {
+		return
+	}
+	const policy = (parsed.runtimeVersion as { policy?: unknown } | undefined)
+		?.policy
+	if (policy !== 'fingerprint') {
+		findings.push({
+			level: 'warning',
+			message: `runtimeVersion is ${JSON.stringify(parsed.runtimeVersion ?? null)}, not { policy: 'fingerprint' }: an OTA can reach a binary whose native code differs.`,
+			fix: "Set runtimeVersion: { policy: 'fingerprint' } in the app config."
+		})
+	}
+	if (
+		nativeDirs.length > 0 &&
+		Array.isArray(parsed.plugins) &&
+		parsed.plugins.length > 0
+	) {
+		findings.push({
+			level: 'warning',
+			message: `${nativeDirs.join(' and ')} are committed while the app config has plugins: EAS builds the committed tree and never applies config plugin changes.`,
+			fix: 'Delete and gitignore the native folders, or run `npx expo prebuild` and commit after every plugin change.'
+		})
+	}
+}
+
+/** Checks what makes a release fail later, or ship the wrong thing. */
+export async function runDoctor(
+	input: DoctorInput,
+	runner: CommandRunner = runSilent
+): Promise<Finding[]> {
+	const findings: Finding[] = []
+	const readFile = input.readFile ?? defaultReadFile
+	await checkProfile(input, findings)
+	await checkTools(input, runner, findings)
+	const nativeDirs = (await checkTrackedFiles(runner, findings, readFile)) ?? []
+	if (input.full) await checkAppConfig(runner, findings, nativeDirs)
+	return findings
+}
+
+function escapeAnnotation(text: string) {
+	return text
+		.replaceAll('%', '%25')
+		.replaceAll('\r', '%0D')
+		.replaceAll('\n', '%0A')
+}
+
+/** One line per finding; GitHub annotations inside Actions. */
+export function formatFindings(
+	findings: Finding[],
+	options: { asWarnings?: boolean; github?: boolean } = {}
+): string {
+	return findings
+		.map((finding) => {
+			const level = options.asWarnings ? 'warning' : finding.level
+			const text = finding.fix
+				? `${finding.message}\nFix: ${finding.fix}`
+				: finding.message
+			return options.github
+				? `::${level} title=expo-release doctor::${escapeAnnotation(text)}`
+				: `${level}: ${text}`
+		})
+		.join('\n')
+}