From 944be5512b4c2375d69bd900302309d2e6f496bd Mon Sep 17 00:00:00 2001 From: Alexey Karimov Date: Mon, 16 Nov 2026 16:52:37 +0500 Subject: [PATCH 1/4] Fail when an SDK removes an option between the previous pin and the current one Comparing this package with an SDK's manifest cannot show 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. `yarn check:options-manifests` now also fetches the manifest of the PREVIOUS pin (scripts/sdk-baseline.json) and fails on every option it has that the current pin's manifest lacks, naming the option, both versions and the accessor that still writes it. A removal is either dealt with (accessor removed or deprecated) or acknowledged in the baseline with a reason. An acknowledgement for an option that was not removed fails too, so the file cannot lie. When native-versions.json moves, the baseline must follow: the check says what to write, and an offline test fails the plain `yarn test` the moment it does not, so a bump cannot skip the comparison. This is not hypothetical: iOS 7.0.0-beta7 removed detect.kill and capture.mach-exceptions, and their accessors lingered until noticed. Pointing the baseline at beta6 reproduces exactly those two findings. For the current pins (Android 7.4.1 -> 7.4.2, iOS 7.0.0-beta7 -> 7.0.0) nothing was removed. Human guided, AI implemented --- docs/launch-options.md | 7 +- scripts/__tests__/published-manifest.test.ts | 167 +++++++++++++++++++ scripts/__tests__/sdk-baseline.test.ts | 27 +++ scripts/cli-check-published-manifests.ts | 43 ++++- scripts/cli-options-sources.ts | 13 +- scripts/published-manifest.ts | 145 ++++++++++++++++ scripts/sdk-baseline.json | 5 + 7 files changed, 404 insertions(+), 3 deletions(-) create mode 100644 scripts/__tests__/sdk-baseline.test.ts create mode 100644 scripts/sdk-baseline.json 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/scripts/__tests__/published-manifest.test.ts b/scripts/__tests__/published-manifest.test.ts index 85be0baf..8e700126 100644 --- a/scripts/__tests__/published-manifest.test.ts +++ b/scripts/__tests__/published-manifest.test.ts @@ -2,11 +2,15 @@ import { ENUM_TS_NAMES, MANIFEST_BASE, checkAccessors, + checkBaseline, checkPublished, + checkRemovals, manifestUrl, + parseBaseline, parseManifest, type Accessor, type AccessorCheckInput, + type AcknowledgedRemoval, type CheckInput, type PublishedManifest, type PublishedOption, @@ -460,3 +464,166 @@ 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: [], + accessorsByKey: new Map(), + ...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 which accessor still writes the removed option', () => { + const [problem] = removal({ current: without('b'), accessorsByKey: new Map([['b', 'detectAndReportKill']]) }); + expect(problem).toContain('detectAndReportKill still writes it.'); + }); + + it('says nothing about an accessor when there is none', () => { + expect(removal({ current: without('b') })[0]).not.toContain('still writes it'); + }); + + it('marks a removed internal option as such', () => { + const previous = manifest([option('a'), option('$$X', { hidden: true })]); + const [problem] = removal({ previous, current: manifest([option('a')]) }); + expect(problem).toContain('REMOVED OPTION $$X (an internal option)'); + }); + + it('does not mention internal for an ordinary option', () => { + expect(removal({ current: without('b') })[0]).not.toContain('internal option'); + }); + + 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); + }); +}); 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..7c93bd90 100644 --- a/scripts/cli-check-published-manifests.ts +++ b/scripts/cli-check-published-manifests.ts @@ -11,7 +11,11 @@ * 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 either dealt with (the + * accessor removed or deprecated) or acknowledged in the baseline with the reason. * * 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 +35,9 @@ import { join } from 'node:path'; import { MANIFEST_BASE, checkAccessors, + checkBaseline, checkPublished, + checkRemovals, manifestUrl, parseManifest, type Platform, @@ -47,6 +53,7 @@ import { optionsDir, pinned, readAccessors, + readBaseline, readEnums, readNoAccessor, } from './cli-options-sources.ts'; @@ -82,6 +89,14 @@ 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(); @@ -133,6 +148,32 @@ 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, + accessorsByKey: new Map(accessors.map((accessor) => [accessor.key, accessor.name])), + }); + 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..f8a72134 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`; /** diff --git a/scripts/published-manifest.ts b/scripts/published-manifest.ts index ab753c0f..4dfd6205 100644 --- a/scripts/published-manifest.ts +++ b/scripts/published-manifest.ts @@ -340,3 +340,148 @@ 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[]; + /** Accessors by the key they write, to say what is left behind. */ + accessorsByKey: ReadonlyMap; +} + +/** + * Every option the previous pin's manifest has and the current one lacks, unless it was acknowledged, + * plus every acknowledgement that no longer matches a removal. Names the option, and the accessor still + * writing it. + */ +export function checkRemovals(input: RemovalCheckInput): string[] { + const { platform, previousVersion, currentVersion, previous, current, acknowledged, accessorsByKey } = 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 accessor = accessorsByKey.get(option.key); + const left = accessor === undefined ? '' : ` ${accessor} still writes it.`; + const internal = option.hidden === true ? ' (an internal option)' : ''; + problems.push( + `REMOVED OPTION ${option.key}${internal} was in the ${platform} ${previousVersion} manifest and is absent ` + + `from ${currentVersion}.${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; +} 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": [] +} From 720d0cb47497a1a7658cdce6bcfb68c468e983ff Mon Sep 17 00:00:00 2001 From: Alexey Karimov Date: Mon, 16 Nov 2026 17:04:44 +0500 Subject: [PATCH 2/4] Address review: report a removed internal option only when this package uses it A removed internal (hidden) option was reported like any other, although the package has no accessor for it and the only exits offered did not fit. But internal options are also the wrapper contract, and one of them matters: the endpoint override (`$$ENDPOINT`) is used by the endpoint accessor, the Expo plugin and the Android meta-data path. NO_ACCESSOR is only a catalogue of known internal keys (nothing uses `$$DEBUG` or `$$WRAPPER` as an option), so it is not the criterion. RELIES_ON_INTERNAL now lists the internal options the code really depends on, with the reason. A removed internal option is reported only when it is listed there or an accessor writes it; the message says "an internal option this package relies on". Dropping `$$DEBUG` and `$$WRAPPER` is silent; dropping `$$ENDPOINT` fails. A test requires every listed key to be a real internal option of both pinned SDKs. Human guided, AI implemented --- .../react-native/src/options/noAccessor.ts | 13 ++++++++ scripts/__tests__/published-manifest.test.ts | 33 +++++++++++++++++-- scripts/__tests__/relies-on-internal.test.ts | 23 +++++++++++++ scripts/cli-check-published-manifests.ts | 3 ++ scripts/cli-options-sources.ts | 8 +++++ scripts/published-manifest.ts | 17 ++++++++-- 6 files changed, 91 insertions(+), 6 deletions(-) create mode 100644 scripts/__tests__/relies-on-internal.test.ts 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 8e700126..4d969c64 100644 --- a/scripts/__tests__/published-manifest.test.ts +++ b/scripts/__tests__/published-manifest.test.ts @@ -551,6 +551,7 @@ describe('checkRemovals', () => { current: manifest([option('a'), option('b'), option('c')], { sdk: 'ios', sdkVersion: '7.0.0' }), acknowledged: [], accessorsByKey: new Map(), + relied: new Set(), ...extra, }); const without = (...keys: string[]): PublishedManifest => @@ -586,10 +587,36 @@ describe('checkRemovals', () => { expect(removal({ current: without('b') })[0]).not.toContain('still writes it'); }); - it('marks a removed internal option as such', () => { + describe('an internal (hidden) option', () => { const previous = manifest([option('a'), option('$$X', { hidden: true })]); - const [problem] = removal({ previous, current: manifest([option('a')]) }); - expect(problem).toContain('REMOVED OPTION $$X (an internal option)'); + 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, accessorsByKey: new Map([['$$X', 'someAccessor']]) }); + 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', () => { 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/cli-check-published-manifests.ts b/scripts/cli-check-published-manifests.ts index 7c93bd90..e49b3190 100644 --- a/scripts/cli-check-published-manifests.ts +++ b/scripts/cli-check-published-manifests.ts @@ -56,6 +56,7 @@ import { readBaseline, readEnums, readNoAccessor, + readReliesOnInternal, } from './cli-options-sources.ts'; const dirFlag = process.argv.indexOf('--dir'); @@ -100,6 +101,7 @@ try { const accessors = readAccessors(); const { enums, withheld } = await readEnums(); const noAccessor = await readNoAccessor(); +const reliesOnInternal = await readReliesOnInternal(); const manifests: Partial> = {}; let failed = false; @@ -168,6 +170,7 @@ for (const platform of ['android', 'ios'] as const) { current: published, acknowledged: baseline.acknowledgedRemovals, accessorsByKey: new Map(accessors.map((accessor) => [accessor.key, accessor.name])), + relied: new Set(Object.keys(reliesOnInternal)), }); report(`${platform} ${previousVersion} -> ${version}`, removals); if (removals.length === 0) { diff --git a/scripts/cli-options-sources.ts b/scripts/cli-options-sources.ts index f8a72134..e5425af0 100644 --- a/scripts/cli-options-sources.ts +++ b/scripts/cli-options-sources.ts @@ -72,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 4dfd6205..5473d928 100644 --- a/scripts/published-manifest.ts +++ b/scripts/published-manifest.ts @@ -442,15 +442,20 @@ export interface RemovalCheckInput { acknowledged: readonly AcknowledgedRemoval[]; /** Accessors by the key they write, to say what is left behind. */ accessorsByKey: ReadonlyMap; + /** + * Internal options this package's code depends on (`RELIES_ON_INTERNAL`: the endpoint override). A + * removed INTERNAL option matters only when it is one of these or an accessor writes it. + */ + relied: ReadonlySet; } /** * Every option the previous pin's manifest has and the current one lacks, unless it was acknowledged, * plus every acknowledgement that no longer matches a removal. Names the option, and the accessor still - * writing it. + * writing it. An internal (hidden) option is reported only when this package depends on it. */ export function checkRemovals(input: RemovalCheckInput): string[] { - const { platform, previousVersion, currentVersion, previous, current, acknowledged, accessorsByKey } = input; + const { platform, previousVersion, currentVersion, previous, current, acknowledged, accessorsByKey, 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)); @@ -466,8 +471,14 @@ export function checkRemovals(input: RemovalCheckInput): string[] { continue; } const accessor = accessorsByKey.get(option.key); + const depends = accessor !== undefined || relied.has(option.key); + // An internal option this package never touches cannot affect it. The wrapper contract is internal + // too ($$ENDPOINT, $$WRAPPER), and losing one of those does, so those are reported. + if (option.hidden === true && !depends) { + continue; + } const left = accessor === undefined ? '' : ` ${accessor} still writes it.`; - const internal = option.hidden === true ? ' (an internal option)' : ''; + 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} Remove or deprecate its accessor and re-extract the fixtures, or, if ` + From 81388deadea42a007a0a71f30ce6a85805c2d5b0 Mon Sep 17 00:00:00 2001 From: Alexey Karimov Date: Mon, 16 Nov 2026 17:23:29 +0500 Subject: [PATCH 3/4] Address review: a removal is dealt with when nothing is left for it The docs, PR text and message said a removal is "either dealt with (accessor removed or deprecated) or acknowledged", but only acknowledgement could pass: the accessor was looked up only to word the message, so deleting it and re-extracting the fixtures, exactly what the message asks for, left CI red. A removed option is now reported only while this package still has something for its key on that platform: a live accessor (one that is not deprecated) or an entry in option-keys.json. Remove or deprecate the accessor and re-extract the fixtures and it clears; acknowledgement stays for the case where React Native keeps the key as an option of its own. The message says what is left ("captureAVPlayer still writes it" or "option-keys.json still lists it"). The accessors considered are those of the platform being checked, so another platform's cannot count. Internal options keep their own rule (reported when relied on). Human guided, AI implemented --- scripts/__tests__/published-manifest.test.ts | 35 ++++++++++++++++---- scripts/cli-check-published-manifests.ts | 21 ++++++++++-- scripts/published-manifest.ts | 35 +++++++++++--------- 3 files changed, 66 insertions(+), 25 deletions(-) diff --git a/scripts/__tests__/published-manifest.test.ts b/scripts/__tests__/published-manifest.test.ts index 4d969c64..3fac0636 100644 --- a/scripts/__tests__/published-manifest.test.ts +++ b/scripts/__tests__/published-manifest.test.ts @@ -550,7 +550,7 @@ describe('checkRemovals', () => { 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: [], - accessorsByKey: new Map(), + live: new Map([['a', 'x'], ['b', 'x'], ['c', 'x'], ['d', 'x']]), relied: new Set(), ...extra, }); @@ -578,13 +578,28 @@ describe('checkRemovals', () => { expect(problems.map((p) => p.match(/REMOVED OPTION (\w+)/)?.[1])).toEqual(['a', 'c']); }); - it('says which accessor still writes the removed option', () => { - const [problem] = removal({ current: without('b'), accessorsByKey: new Map([['b', 'detectAndReportKill']]) }); - expect(problem).toContain('detectAndReportKill still writes it.'); + 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'); }); - it('says nothing about an accessor when there is none', () => { - expect(removal({ current: without('b') })[0]).not.toContain('still writes it'); + 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', () => { @@ -601,7 +616,7 @@ describe('checkRemovals', () => { }); it('is reported when an accessor writes it, naming the accessor', () => { - const [problem] = removal({ previous, current, accessorsByKey: new Map([['$$X', 'someAccessor']]) }); + 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.'); }); @@ -623,6 +638,12 @@ describe('checkRemovals', () => { 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([]); }); diff --git a/scripts/cli-check-published-manifests.ts b/scripts/cli-check-published-manifests.ts index e49b3190..2e5eb596 100644 --- a/scripts/cli-check-published-manifests.ts +++ b/scripts/cli-check-published-manifests.ts @@ -14,8 +14,9 @@ * 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 either dealt with (the - * accessor removed or deprecated) or acknowledged in the baseline with the reason. + * 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 @@ -116,6 +117,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, `${accessor.name} still writes it`); + } + } + return live; +} + for (const platform of ['android', 'ios'] as const) { const version = pinned[platform].sdk; const label = `${platform} ${version}`; @@ -169,7 +184,7 @@ for (const platform of ['android', 'ios'] as const) { previous, current: published, acknowledged: baseline.acknowledgedRemovals, - accessorsByKey: new Map(accessors.map((accessor) => [accessor.key, accessor.name])), + live: liveKeys(platform), relied: new Set(Object.keys(reliesOnInternal)), }); report(`${platform} ${previousVersion} -> ${version}`, removals); diff --git a/scripts/published-manifest.ts b/scripts/published-manifest.ts index 5473d928..eb895620 100644 --- a/scripts/published-manifest.ts +++ b/scripts/published-manifest.ts @@ -440,22 +440,28 @@ export interface RemovalCheckInput { previous: PublishedManifest; current: PublishedManifest; acknowledged: readonly AcknowledgedRemoval[]; - /** Accessors by the key they write, to say what is left behind. */ - accessorsByKey: ReadonlyMap; /** - * Internal options this package's code depends on (`RELIES_ON_INTERNAL`: the endpoint override). A - * removed INTERNAL option matters only when it is one of these or an accessor writes it. + * 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, unless it was acknowledged, - * plus every acknowledgement that no longer matches a removal. Names the option, and the accessor still - * writing it. An internal (hidden) option is reported only when this package depends on it. + * 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, accessorsByKey, relied } = input; + 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)); @@ -470,18 +476,17 @@ export function checkRemovals(input: RemovalCheckInput): string[] { if (acknowledgedKeys.has(option.key)) { continue; } - const accessor = accessorsByKey.get(option.key); - const depends = accessor !== undefined || relied.has(option.key); - // An internal option this package never touches cannot affect it. The wrapper contract is internal - // too ($$ENDPOINT, $$WRAPPER), and losing one of those does, so those are reported. - if (option.hidden === true && !depends) { + 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 left = accessor === undefined ? '' : ` ${accessor} still writes it.`; 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} Remove or deprecate its accessor and re-extract the fixtures, or, if ` + + `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.', ); } From 52c1b7899d26b3aedc6b454fe446707e2aa3f143 Mon Sep 17 00:00:00 2001 From: Alexey Karimov Date: Mon, 16 Nov 2026 18:12:28 +0500 Subject: [PATCH 4/4] Address review: tell a shared accessor to move, not to be deprecated A removed option can still be written by a SHARED accessor (BugseeLaunchOptions). When only one SDK dropped it, "remove or deprecate its accessor" breaks the platform that still has the option, and the acknowledgement wording is false. The message now says the accessor is shared by both platforms and must be moved to the class of the platform that still has the option, or removed if both SDKs dropped it. The wording is a pure, tested function (describeLiveAccessor) used by the check. Human guided, AI implemented --- scripts/__tests__/published-manifest.test.ts | 20 ++++++++++++++++++ scripts/cli-check-published-manifests.ts | 3 ++- scripts/published-manifest.ts | 22 ++++++++++++++++++++ 3 files changed, 44 insertions(+), 1 deletion(-) diff --git a/scripts/__tests__/published-manifest.test.ts b/scripts/__tests__/published-manifest.test.ts index 3fac0636..479f0660 100644 --- a/scripts/__tests__/published-manifest.test.ts +++ b/scripts/__tests__/published-manifest.test.ts @@ -5,6 +5,7 @@ import { checkBaseline, checkPublished, checkRemovals, + describeLiveAccessor, manifestUrl, parseBaseline, parseManifest, @@ -675,3 +676,22 @@ describe('checkRemovals', () => { 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/cli-check-published-manifests.ts b/scripts/cli-check-published-manifests.ts index 2e5eb596..af79f782 100644 --- a/scripts/cli-check-published-manifests.ts +++ b/scripts/cli-check-published-manifests.ts @@ -39,6 +39,7 @@ import { checkBaseline, checkPublished, checkRemovals, + describeLiveAccessor, manifestUrl, parseManifest, type Platform, @@ -125,7 +126,7 @@ function liveKeys(platform: Platform): Map { } for (const accessor of accessorsFor(accessors, platform)) { if (accessor.deprecated === undefined) { - live.set(accessor.key, `${accessor.name} still writes it`); + live.set(accessor.key, describeLiveAccessor(accessor.name, accessor.owner, platform)); } } return live; diff --git a/scripts/published-manifest.ts b/scripts/published-manifest.ts index eb895620..ae37bf9e 100644 --- a/scripts/published-manifest.ts +++ b/scripts/published-manifest.ts @@ -501,3 +501,25 @@ export function checkRemovals(input: RemovalCheckInput): string[] { } 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` + ); +}