diff --git a/docs/launch-options.md b/docs/launch-options.md index c6ebaf5e..f9277c18 100644 --- a/docs/launch-options.md +++ b/docs/launch-options.md @@ -18,7 +18,12 @@ a test fails when either SDK registers an option this package has no accessor fo `download.bugsee.com/sdk/options//.json` with this package. It fails when an SDK publishes an option this package lacks (named in the message), or an option whose type, default or enum constants differ. It does not complain about an option this package has and the SDK does not publish: the package may define options of its own, -which the SDK ignores. The tables below are generated from the accessors and those manifests +which the SDK ignores. The same check also compares the pinned release's manifest with the one for the **previous pin** +(`scripts/sdk-baseline.json`) and fails on any option the newer one no longer has: the SDK removed it, and its accessor and +docs are now dead. That is the one place a removal can be seen, because this package's own option set cannot show it. When +`native-versions.json` moves, set `previous` to the old `current` and `current` to the new pin in that file; a removal is +either dealt with (accessor removed or deprecated) or acknowledged there, with the reason. The tables below are generated +from the accessors and those manifests (`node scripts/cli-generate-launch-options-doc.ts`), and the check fails when they are stale. Options a *newer* SDK adds are reachable with `options.setCustomOption(key, value)` until the package catches up. diff --git a/packages/react-native/src/options/noAccessor.ts b/packages/react-native/src/options/noAccessor.ts index e0e03be8..b3395b09 100644 --- a/packages/react-native/src/options/noAccessor.ts +++ b/packages/react-native/src/options/noAccessor.ts @@ -14,3 +14,16 @@ export const NO_ACCESSOR: Readonly> = { 'com.bugsee.option.$$ENDPOINT': 'reached through the `endpoint` accessor', endpoint: 'reached through the `endpoint` accessor', }; + +/** + * Internal (hidden) SDK options this package's code really uses, with what it uses them for. When an SDK + * drops one of these the package breaks, so the removal check reports it; an internal option that is not + * listed here (`$$DEBUG`, `$$WRAPPER`: the wrapper registers itself through `setWrapper`, not the option) + * is not this package's concern when it disappears. + * + * Add an entry when code starts to depend on another internal option. + */ +export const RELIES_ON_INTERNAL: Readonly> = { + 'com.bugsee.option.$$ENDPOINT': + 'the endpoint override: the `endpoint` accessor, the Expo plugin and the Android manifest meta-data path', +}; diff --git a/scripts/__tests__/published-manifest.test.ts b/scripts/__tests__/published-manifest.test.ts index 85be0baf..479f0660 100644 --- a/scripts/__tests__/published-manifest.test.ts +++ b/scripts/__tests__/published-manifest.test.ts @@ -2,11 +2,16 @@ import { ENUM_TS_NAMES, MANIFEST_BASE, checkAccessors, + checkBaseline, checkPublished, + checkRemovals, + describeLiveAccessor, manifestUrl, + parseBaseline, parseManifest, type Accessor, type AccessorCheckInput, + type AcknowledgedRemoval, type CheckInput, type PublishedManifest, type PublishedOption, @@ -460,3 +465,233 @@ describe('checkAccessors', () => { }); }); }); + +describe('parseBaseline', () => { + const valid = { + android: { previous: '7.4.1', current: '7.4.2' }, + ios: { previous: '7.0.0-beta7', current: '7.0.0' }, + acknowledgedRemovals: [{ platform: 'ios', key: 'k', reason: 'because' }], + }; + const parse = (value: unknown): ReturnType => parseBaseline(JSON.stringify(value), 'the-source'); + + it('reads the versions and the acknowledgements', () => { + expect(parse(valid)).toEqual(valid); + }); + + it('treats a missing acknowledgements list as none', () => { + expect(parse({ android: valid.android, ios: valid.ios }).acknowledgedRemovals).toEqual([]); + }); + + it.each([ + ['not JSON', '{ nope'], + ['a list', '[]'], + ['null', 'null'], + ])('refuses %s, naming the source', (_name, text) => { + expect(() => parseBaseline(text, 'the-source')).toThrow(/the-source/); + }); + + it.each([ + ['no android', { ...valid, android: undefined }], + ['an android without previous', { ...valid, android: { current: '1' } }], + ['an android without current', { ...valid, android: { previous: '1' } }], + ['an android version that is a number', { ...valid, android: { previous: 1, current: '2' } }], + ['no ios', { ...valid, ios: undefined }], + ['an ios that is a list', { ...valid, ios: [] }], + ])('refuses %s, naming the platform', (_name, value) => { + expect(() => parse(value)).toThrow(/the-source: (android|ios) needs a "previous" and a "current" version/); + }); + + it('refuses acknowledgements that are not a list', () => { + expect(() => parse({ ...valid, acknowledgedRemovals: {} })).toThrow(/acknowledgedRemovals must be a list/); + }); + + it.each([ + ['not an object', 'x'], + ['an unknown platform', { platform: 'web', key: 'k', reason: 'r' }], + ['no key', { platform: 'ios', reason: 'r' }], + ['an empty key', { platform: 'ios', key: '', reason: 'r' }], + ['no reason', { platform: 'ios', key: 'k' }], + ['a blank reason', { platform: 'ios', key: 'k', reason: ' ' }], + ])('refuses an acknowledgement with %s, naming it', (_name, entry) => { + expect(() => parse({ ...valid, acknowledgedRemovals: [valid.acknowledgedRemovals[0], entry] })).toThrow( + /acknowledgedRemovals #1 needs a platform, a key and a reason/, + ); + }); +}); + +describe('checkBaseline', () => { + it('is empty when the baseline describes the pin', () => { + expect(checkBaseline('android', { previous: '7.4.1', current: '7.4.2' }, '7.4.2')).toEqual([]); + }); + + it('says what to write when the pin moved and the baseline did not', () => { + const [problem] = checkBaseline('android', { previous: '7.4.0', current: '7.4.1' }, '7.4.2'); + expect(problem).toContain('native-versions.json pins android 7.4.2'); + expect(problem).toContain('says the current android version is 7.4.1'); + expect(problem).toContain('Set "previous" to 7.4.1 and "current" to 7.4.2'); + }); + + it('refuses a baseline whose two versions are the same', () => { + expect(checkBaseline('ios', { previous: '7.0.0', current: '7.0.0' }, '7.0.0')).toEqual([ + 'scripts/sdk-baseline.json has the same previous and current ios version, 7.0.0', + ]); + }); + + it('reports only the pin mismatch when both are wrong', () => { + expect(checkBaseline('ios', { previous: '1', current: '1' }, '2')).toHaveLength(1); + }); +}); + +describe('checkRemovals', () => { + const removal = (extra: Partial[0]> = {}): string[] => + checkRemovals({ + platform: 'ios', + previousVersion: '7.0.0-beta6', + currentVersion: '7.0.0', + previous: manifest([option('a'), option('b'), option('c')], { sdk: 'ios', sdkVersion: '7.0.0-beta6' }), + current: manifest([option('a'), option('b'), option('c')], { sdk: 'ios', sdkVersion: '7.0.0' }), + acknowledged: [], + live: new Map([['a', 'x'], ['b', 'x'], ['c', 'x'], ['d', 'x']]), + relied: new Set(), + ...extra, + }); + const without = (...keys: string[]): PublishedManifest => + manifest([option('a'), option('b'), option('c')].filter((o) => !keys.includes(o.key)), { sdk: 'ios' }); + const ack = (key: string, platform: 'android' | 'ios' = 'ios'): AcknowledgedRemoval => ({ platform, key, reason: 'r' }); + + it('is empty when nothing was removed', () => { + expect(removal()).toEqual([]); + }); + + it('is empty when the current pin only adds options', () => { + expect(removal({ current: manifest([option('a'), option('b'), option('c'), option('d')]) })).toEqual([]); + }); + + it('names an option the current pin no longer has, with both versions', () => { + const problems = removal({ current: without('b') }); + expect(problems).toHaveLength(1); + expect(problems[0]).toContain('REMOVED OPTION b was in the ios 7.0.0-beta6 manifest and is absent from 7.0.0.'); + expect(problems[0]).toContain('acknowledge it in scripts/sdk-baseline.json'); + }); + + it('lists every removal, in key order', () => { + const problems = removal({ current: without('c', 'a') }); + expect(problems.map((p) => p.match(/REMOVED OPTION (\w+)/)?.[1])).toEqual(['a', 'c']); + }); + + it('says what is still left for the removed option', () => { + const [problem] = removal({ current: without('b'), live: new Map([['b', 'detectAndReportKill still writes it']]) }); + expect(problem).toContain('absent from 7.0.0. detectAndReportKill still writes it. Remove or deprecate'); + }); + + describe('a removal that was dealt with', () => { + it('is not reported once nothing is left for the key: the accessor is gone and the fixtures re-extracted', () => { + expect(removal({ current: without('b'), live: new Map([['a', 'x'], ['c', 'x']]) })).toEqual([]); + }); + + it('is reported while only a key-list entry is left, so the fixtures must be re-extracted', () => { + const [problem] = removal({ current: without('b'), live: new Map([['b', 'option-keys.json still lists it']]) }); + expect(problem).toContain('option-keys.json still lists it.'); + }); + + it('is reported while a live accessor is left', () => { + expect(removal({ current: without('b'), live: new Map([['b', 'oldAccessor still writes it']]) })).toHaveLength(1); + }); + + it('only counts what is left for the removed key, not for the others', () => { + expect(removal({ current: without('b'), live: new Map([['a', 'x']]) })).toEqual([]); + }); + }); + + describe('an internal (hidden) option', () => { + const previous = manifest([option('a'), option('$$X', { hidden: true })]); + const current = manifest([option('a')]); + + it('is not reported when this package does not touch it', () => { + expect(removal({ previous, current })).toEqual([]); + }); + + it('is reported when this package relies on it without an accessor, such as the endpoint override', () => { + const [problem] = removal({ previous, current, relied: new Set(['$$X']) }); + expect(problem).toContain('REMOVED OPTION $$X (an internal option this package relies on)'); + }); + + it('is reported when an accessor writes it, naming the accessor', () => { + const [problem] = removal({ previous, current, live: new Map([['$$X', 'someAccessor still writes it']]) }); + expect(problem).toContain('$$X (an internal option this package relies on)'); + expect(problem).toContain('someAccessor still writes it.'); + }); + + it('can be acknowledged like any other', () => { + expect(removal({ previous, current, relied: new Set(['$$X']), acknowledged: [ack('$$X')] })).toEqual([]); + }); + + it('is not mistaken for stale when it was removed and this package does not touch it', () => { + expect(removal({ previous, current, acknowledged: [ack('$$X')] })).toEqual([]); + }); + }); + + it('reports an ordinary removed option even when this package depends on nothing else', () => { + expect(removal({ current: without('b'), relied: new Set(['unrelated']) })).toHaveLength(1); + }); + + it('does not mention internal for an ordinary option', () => { + expect(removal({ current: without('b') })[0]).not.toContain('internal option'); + }); + + it('says nothing about what is left when it only depends on the key being relied on', () => { + const previous = manifest([option('$$X', { hidden: true })]); + const [problem] = removal({ previous, current: manifest([]), live: new Map(), relied: new Set(['$$X']) }); + expect(problem).toContain('absent from 7.0.0. Remove or deprecate'); + }); + + it('accepts a removal that was acknowledged', () => { + expect(removal({ current: without('b'), acknowledged: [ack('b')] })).toEqual([]); + }); + + it('only accepts an acknowledgement for the same platform', () => { + const problems = removal({ current: without('b'), acknowledged: [ack('b', 'android')] }); + expect(problems.filter((p) => p.startsWith('REMOVED OPTION b'))).toHaveLength(1); + }); + + it('accepts some removals acknowledged and reports the rest', () => { + const problems = removal({ current: without('a', 'b'), acknowledged: [ack('a')] }); + expect(problems).toHaveLength(1); + expect(problems[0]).toContain('REMOVED OPTION b'); + }); + + it('reports an acknowledgement for an option that was not removed, so the file cannot lie', () => { + const problems = removal({ acknowledged: [ack('a')] }); + expect(problems).toEqual([ + 'scripts/sdk-baseline.json acknowledges the removal of a on ios, but it was not removed between 7.0.0-beta6 and 7.0.0: delete the entry', + ]); + }); + + it('ignores an acknowledgement meant for the other platform', () => { + expect(removal({ acknowledged: [ack('a', 'android')] })).toEqual([]); + }); + + it('reports a stale acknowledgement next to a real removal', () => { + const problems = removal({ current: without('b'), acknowledged: [ack('a')] }); + expect(problems).toHaveLength(2); + }); +}); + +describe('describeLiveAccessor', () => { + it('says a platform\'s own accessor still writes the key', () => { + expect(describeLiveAccessor('captureAVPlayer', 'ios', 'ios')).toBe('captureAVPlayer still writes it'); + expect(describeLiveAccessor('videoMode', 'android', 'android')).toBe('videoMode still writes it'); + }); + + it('says a shared accessor must be moved to the platform that still has the option, not deprecated', () => { + const text = describeLiveAccessor('foo', 'base', 'android'); + expect(text).toContain('foo still writes it, and is shared by both platforms (BugseeLaunchOptions)'); + expect(text).toContain('if only the android SDK dropped the option, move it to IOSLaunchOptions, since iOS still has it'); + expect(text).toContain('if both did, remove it'); + }); + + it('names the other platform\'s class and name for each platform', () => { + expect(describeLiveAccessor('foo', 'base', 'ios')).toContain('move it to AndroidLaunchOptions, since Android still has it'); + expect(describeLiveAccessor('foo', 'base', 'ios')).toContain('only the ios SDK dropped'); + }); +}); diff --git a/scripts/__tests__/relies-on-internal.test.ts b/scripts/__tests__/relies-on-internal.test.ts new file mode 100644 index 00000000..580e3b40 --- /dev/null +++ b/scripts/__tests__/relies-on-internal.test.ts @@ -0,0 +1,23 @@ +import { RELIES_ON_INTERNAL } from '../../packages/react-native/src/options/noAccessor'; +import androidManifest from '../../packages/react-native/src/options/android-options-manifest.json'; +import iosManifest from '../../packages/react-native/src/options/ios-options-manifest.json'; + +/** + * The internal options the package's code depends on must be real, current ones: an entry for an option + * no pinned SDK registers would silence nothing and mislead whoever reads the list. + */ +describe('RELIES_ON_INTERNAL', () => { + const hidden = (options: { key: string; hidden?: boolean }[]): Set => + new Set(options.filter((option) => option.hidden === true).map((option) => option.key)); + + it.each(Object.keys(RELIES_ON_INTERNAL))('%s is an internal option of both pinned SDKs', (key) => { + expect(hidden(androidManifest.options).has(key)).toBe(true); + expect(hidden(iosManifest.options).has(key)).toBe(true); + }); + + it('gives every entry a reason', () => { + for (const reason of Object.values(RELIES_ON_INTERNAL)) { + expect(reason.trim()).not.toBe(''); + } + }); +}); diff --git a/scripts/__tests__/sdk-baseline.test.ts b/scripts/__tests__/sdk-baseline.test.ts new file mode 100644 index 00000000..d12ab9fb --- /dev/null +++ b/scripts/__tests__/sdk-baseline.test.ts @@ -0,0 +1,27 @@ +import { readFileSync } from 'node:fs'; +import { join } from 'node:path'; +import { checkBaseline, parseBaseline } from '../published-manifest'; + +const root = join(__dirname, '..', '..'); +const baseline = parseBaseline(readFileSync(join(root, 'scripts', 'sdk-baseline.json'), 'utf8'), 'scripts/sdk-baseline.json'); +const pinned = JSON.parse(readFileSync(join(root, 'native-versions.json'), 'utf8')) as { + android: { sdk: string }; + ios: { sdk: string }; +}; + +/** + * The offline half of the removal check. The check itself compares the previous pin's published manifest + * with the current one and needs the network; this fails the plain test run the moment the pin moves + * without the baseline, so a bump cannot skip the removal comparison by forgetting to update it. + */ +describe('scripts/sdk-baseline.json', () => { + it.each(['android', 'ios'] as const)('describes the %s pin in native-versions.json', (platform) => { + expect(checkBaseline(platform, baseline[platform], pinned[platform].sdk)).toEqual([]); + }); + + it('acknowledges removals only with a reason', () => { + for (const entry of baseline.acknowledgedRemovals) { + expect(entry.reason.trim()).not.toBe(''); + } + }); +}); diff --git a/scripts/cli-check-published-manifests.ts b/scripts/cli-check-published-manifests.ts index c383592b..af79f782 100644 --- a/scripts/cli-check-published-manifests.ts +++ b/scripts/cli-check-published-manifests.ts @@ -11,7 +11,12 @@ * hold the SDK's, and the package's enums have the SDK's constants. A missing option is reported by * name; * - docs/launch-options.md is what the generator renders from these, so its type and default of every - * option are the SDK's. + * option are the SDK's; + * - no option the PREVIOUS pin's manifest has is missing from the current one (scripts/sdk-baseline.json + * names the previous version). That is the one place a removal can be seen: this package may have + * options of its own, so comparing against its set proves nothing. A removal is dealt with when nothing + * is left for it (the accessor removed or deprecated and the fixtures re-extracted), or acknowledged in + * the baseline with the reason when React Native keeps the key as an option of its own. * * It is deliberately one-directional. An option this package has and the SDK does not publish is fine: * the package can have options of its own, sent to the SDK (which ignores them) and acted on only in @@ -31,7 +36,10 @@ import { join } from 'node:path'; import { MANIFEST_BASE, checkAccessors, + checkBaseline, checkPublished, + checkRemovals, + describeLiveAccessor, manifestUrl, parseManifest, type Platform, @@ -47,8 +55,10 @@ import { optionsDir, pinned, readAccessors, + readBaseline, readEnums, readNoAccessor, + readReliesOnInternal, } from './cli-options-sources.ts'; const dirFlag = process.argv.indexOf('--dir'); @@ -82,9 +92,18 @@ async function load(platform: Platform, version: string): Promise { throw new Error(`could not fetch ${url}: ${failure}`); } +let baseline: ReturnType; +try { + baseline = readBaseline(); +} catch (error) { + console.error((error as Error).message); + process.exit(1); +} + const accessors = readAccessors(); const { enums, withheld } = await readEnums(); const noAccessor = await readNoAccessor(); +const reliesOnInternal = await readReliesOnInternal(); const manifests: Partial> = {}; let failed = false; @@ -99,6 +118,20 @@ function report(label: string, problems: string[]): void { } } +/** What this package still has for each key on a platform: a live accessor, or an entry in the key list. */ +function liveKeys(platform: Platform): Map { + const live = new Map(); + for (const key of [...keys.shared, ...keys[platform]]) { + live.set(key, 'option-keys.json still lists it'); + } + for (const accessor of accessorsFor(accessors, platform)) { + if (accessor.deprecated === undefined) { + live.set(accessor.key, describeLiveAccessor(accessor.name, accessor.owner, platform)); + } + } + return live; +} + for (const platform of ['android', 'ios'] as const) { const version = pinned[platform].sdk; const label = `${platform} ${version}`; @@ -133,6 +166,33 @@ for (const platform of ['android', 'ios'] as const) { if (problems.length === 0) { console.log(`${label}: aligned (${published.options.length} published options)`); } + + // Options the SDK removed since the previous pin: its own manifests are the only honest source, since + // this package may have options of its own that the SDK never had. + const baselineProblems = checkBaseline(platform, baseline[platform], version); + if (baselineProblems.length > 0) { + report(`${label} (baseline)`, baselineProblems); + } else { + const { previous: previousVersion } = baseline[platform]; + const previous = parseManifest( + await load(platform, previousVersion), + `${platform} ${previousVersion} manifest`, + ); + const removals = checkRemovals({ + platform, + previousVersion, + currentVersion: version, + previous, + current: published, + acknowledged: baseline.acknowledgedRemovals, + live: liveKeys(platform), + relied: new Set(Object.keys(reliesOnInternal)), + }); + report(`${platform} ${previousVersion} -> ${version}`, removals); + if (removals.length === 0) { + console.log(`${platform} ${previousVersion} -> ${version}: no option removed without being dealt with`); + } + } } catch (error) { failed = true; console.error(`${label}: ${(error as Error).message}`); diff --git a/scripts/cli-options-sources.ts b/scripts/cli-options-sources.ts index e4c2a127..e5425af0 100644 --- a/scripts/cli-options-sources.ts +++ b/scripts/cli-options-sources.ts @@ -3,7 +3,13 @@ import { readFileSync } from 'node:fs'; import { join } from 'node:path'; import { pathToFileURL } from 'node:url'; import { parseAccessors, type AccessorInfo } from './option-accessors.ts'; -import { parseManifest, type PublishedManifest, type PublishedOption } from './published-manifest.ts'; +import { + parseBaseline, + parseManifest, + type PublishedManifest, + type SdkBaseline, + type PublishedOption, +} from './published-manifest.ts'; export const root = join(import.meta.dirname, '..'); export const optionsDir = join(root, 'packages', 'react-native', 'src', 'options'); @@ -18,6 +24,11 @@ export const keys = readJson<{ shared: string[]; ios: string[]; android: string[ join(optionsDir, 'option-keys.json'), ); +/** The pin before the current one, and the removals already dealt with (scripts/sdk-baseline.json). */ +export function readBaseline(): SdkBaseline { + return parseBaseline(readFileSync(join(root, 'scripts', 'sdk-baseline.json'), 'utf8'), 'scripts/sdk-baseline.json'); +} + export const fixtureName = (platform: 'android' | 'ios'): string => `${platform}-options-manifest.json`; /** @@ -61,6 +72,14 @@ export async function readEnums(): Promise<{ return { enums, withheld }; } +/** The internal SDK options this package's code depends on (RELIES_ON_INTERNAL). */ +export async function readReliesOnInternal(): Promise> { + const module = (await import(pathToFileURL(join(optionsDir, 'noAccessor.ts')).href)) as { + RELIES_ON_INTERNAL: Record; + }; + return module.RELIES_ON_INTERNAL; +} + export async function readNoAccessor(): Promise> { const module = (await import(pathToFileURL(join(optionsDir, 'noAccessor.ts')).href)) as { NO_ACCESSOR: Record; diff --git a/scripts/published-manifest.ts b/scripts/published-manifest.ts index ab753c0f..ae37bf9e 100644 --- a/scripts/published-manifest.ts +++ b/scripts/published-manifest.ts @@ -340,3 +340,186 @@ function checkType( ? [] : [`${tsName} has the constants [${have.join(', ')}] but ${name} in the SDK has [${want.join(', ')}] (${option.key})`]; } + +// --------------------------------------------------------------------------- +// Options an SDK removed between the previous pin and the current one +// --------------------------------------------------------------------------- + +/** + * The pin before the current one, per platform, and the removals React Native has dealt with. + * + * Comparing this package with an SDK's manifest cannot find a REMOVED option: the package may have + * options of its own, so "we have it, the SDK does not" proves nothing. The SDK's own manifests can: an + * option in the previous pin's manifest and absent from the current one was removed by the SDK, and the + * accessor and docs for it are now dead. (iOS 7.0.0-beta7 dropped `detect.kill` and + * `capture.mach-exceptions` this way, and the accessors for them lingered until someone noticed.) + */ +export interface SdkBaseline { + android: { previous: string; current: string }; + ios: { previous: string; current: string }; + /** Removals that were dealt with deliberately, each with the reason. */ + acknowledgedRemovals: AcknowledgedRemoval[]; +} + +export interface AcknowledgedRemoval { + platform: Platform; + key: string; + reason: string; +} + +function versionPair(value: unknown, platform: string, source: string): { previous: string; current: string } { + if (!isObject(value) || typeof value.previous !== 'string' || typeof value.current !== 'string') { + throw new Error(`${source}: ${platform} needs a "previous" and a "current" version`); + } + return { previous: value.previous, current: value.current }; +} + +/** Rejects a baseline that is malformed, rather than comparing against half of one. */ +export function parseBaseline(text: string, source: string): SdkBaseline { + let parsed: unknown; + try { + parsed = JSON.parse(text); + } catch { + throw new Error(`${source} is not valid JSON`); + } + if (!isObject(parsed)) { + throw new Error(`${source} is not a baseline object`); + } + const acknowledged = parsed.acknowledgedRemovals ?? []; + if (!Array.isArray(acknowledged)) { + throw new Error(`${source}: acknowledgedRemovals must be a list`); + } + const acknowledgedRemovals = acknowledged.map((entry: unknown, index: number): AcknowledgedRemoval => { + const valid = + isObject(entry) && + (entry.platform === 'android' || entry.platform === 'ios') && + typeof entry.key === 'string' && + entry.key !== '' && + typeof entry.reason === 'string' && + entry.reason.trim() !== ''; + if (!valid) { + throw new Error(`${source}: acknowledgedRemovals #${index} needs a platform, a key and a reason`); + } + const { platform, key, reason } = entry as unknown as AcknowledgedRemoval; + return { platform, key, reason }; + }); + return { + android: versionPair(parsed.android, 'android', source), + ios: versionPair(parsed.ios, 'ios', source), + acknowledgedRemovals, + }; +} + +/** + * Problems with the baseline itself: it must describe the pin it sits next to, and its two versions + * must differ. Moving the pin without updating it is exactly when the removal check has to run, so this + * says what to write. + */ +export function checkBaseline( + platform: Platform, + baseline: { previous: string; current: string }, + pinnedVersion: string, +): string[] { + if (baseline.current !== pinnedVersion) { + return [ + `native-versions.json pins ${platform} ${pinnedVersion}, but scripts/sdk-baseline.json says the current ` + + `${platform} version is ${baseline.current}. Set "previous" to ${baseline.current} and "current" to ` + + `${pinnedVersion}; the options removed between them are then checked.`, + ]; + } + if (baseline.previous === baseline.current) { + return [`scripts/sdk-baseline.json has the same previous and current ${platform} version, ${baseline.current}`]; + } + return []; +} + +export interface RemovalCheckInput { + platform: Platform; + previousVersion: string; + currentVersion: string; + previous: PublishedManifest; + current: PublishedManifest; + acknowledged: readonly AcknowledgedRemoval[]; + /** + * What this package still has for a key, by key: a live accessor on this platform (one that is not + * deprecated) or an entry in the key list. A removed option is "dealt with" when nothing is left, so it + * is reported only while its key is here; removing or deprecating the accessor and re-extracting the + * fixtures clears it. The value says what is left, for the message. + */ + live: ReadonlyMap; + /** + * Internal options this package's code depends on (`RELIES_ON_INTERNAL`: the endpoint override). They + * have no accessor to remove, so losing one is reported until it is acknowledged. + */ + relied: ReadonlySet; +} + +/** + * Every option the previous pin's manifest has and the current one lacks that this package still has + * something for (a live accessor, a key-list entry, or, for an internal option, a dependency), unless it + * was acknowledged; plus every acknowledgement that no longer matches a removal. A removal is dealt with + * when nothing is left: remove or deprecate the accessor and re-extract the fixtures. + */ +export function checkRemovals(input: RemovalCheckInput): string[] { + const { platform, previousVersion, currentVersion, previous, current, acknowledged, live, relied } = input; + const here = acknowledged.filter((entry) => entry.platform === platform); + const acknowledgedKeys = new Set(here.map((entry) => entry.key)); + const currentKeys = new Set(current.options.map((option) => option.key)); + const problems: string[] = []; + + const removed = previous.options + .filter((option) => !currentKeys.has(option.key)) + .sort((a, b) => a.key.localeCompare(b.key)); + const removedKeys = new Set(removed.map((option) => option.key)); + + for (const option of removed) { + if (acknowledgedKeys.has(option.key)) { + continue; + } + const left = live.get(option.key); + const depends = left !== undefined || relied.has(option.key); + // Nothing left in this package for the key: the removal is dealt with. (An internal option this + // package never touches cannot affect it either; the wrapper contract, $$ENDPOINT, is `relied`.) + if (!depends) { + continue; + } + const internal = option.hidden === true ? ' (an internal option this package relies on)' : ''; + problems.push( + `REMOVED OPTION ${option.key}${internal} was in the ${platform} ${previousVersion} manifest and is absent ` + + `from ${currentVersion}.${left === undefined ? '' : ` ${left}.`} Remove or deprecate its accessor and re-extract the fixtures, or, if ` + + 'React Native keeps it as an option of its own, acknowledge it in scripts/sdk-baseline.json with the reason.', + ); + } + + for (const entry of here) { + if (!removedKeys.has(entry.key)) { + problems.push( + `scripts/sdk-baseline.json acknowledges the removal of ${entry.key} on ${platform}, but it was not ` + + `removed between ${previousVersion} and ${currentVersion}: delete the entry`, + ); + } + } + return problems; +} + +/** + * What an accessor that still writes a removed key means for the person fixing it. A platform's own + * accessor is simply dead: remove or deprecate it. A SHARED one (on the base class) serves both + * platforms, so deprecating it would break the platform that still has the option; it has to be moved to + * that platform's class, or removed if both SDKs dropped the option. + */ +export function describeLiveAccessor( + name: string, + owner: 'base' | 'android' | 'ios', + platform: Platform, +): string { + if (owner !== 'base') { + return `${name} still writes it`; + } + const other = platform === 'android' ? 'iOS' : 'Android'; + const own = platform === 'android' ? 'IOSLaunchOptions' : 'AndroidLaunchOptions'; + return ( + `${name} still writes it, and is shared by both platforms (BugseeLaunchOptions): if only the ${platform} SDK ` + + `dropped the option, move it to ${own}, since ${other} still has it; if both did, remove it` + ); +} diff --git a/scripts/sdk-baseline.json b/scripts/sdk-baseline.json new file mode 100644 index 00000000..23712b6f --- /dev/null +++ b/scripts/sdk-baseline.json @@ -0,0 +1,5 @@ +{ + "android": { "previous": "7.4.1", "current": "7.4.2" }, + "ios": { "previous": "7.0.0-beta7", "current": "7.0.0" }, + "acknowledgedRemovals": [] +}