From a24d30206503f8f4b1888424894cb29b26e06fc4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 16 Jul 2026 06:17:41 +0000 Subject: [PATCH 1/3] chore: baseline-free production-exports cleanup (#1276) Classify and burn down the 32 baseline-tolerated unused production exports. - Live seams: annotate with @internal JSDoc visibility tags (test hooks, introspection helpers, public install-source constant) so fallow no longer treats them as dead production exports. - Wrappers: collapse re-export wrappers in commands/index.ts (ref/selector) and daemon/lease-context.ts (buildLeaseDiagnosticsContext); update all importers to pull directly from the source module. - Stale baseline entry: remove the non-existent resetAndroidMultiTouchHelperInstallCache entry. - Empty fallow-baselines/production-unused-exports.json so check:production-exports now fails loudly on any new dead export. Fixes #1276 Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../production-unused-exports.json | 36 +------------------ src/cli/parser/args.ts | 3 ++ src/cli/parser/command-suggestions.ts | 3 ++ src/cloud-webdriver/aws-device-farm.ts | 6 ++++ src/cloud-webdriver/browserstack.ts | 6 ++++ src/commands/command-metadata.ts | 3 ++ src/commands/command-surface.ts | 3 ++ src/commands/index.ts | 5 +-- .../runtime/__tests__/test-utils/index.ts | 2 +- .../interaction/runtime/gestures.test.ts | 2 +- .../interaction/runtime/index.test.ts | 3 +- .../interaction/runtime/interactions.test.ts | 2 +- .../interaction/runtime/resolution.test.ts | 2 +- .../interaction/runtime/selector-read.test.ts | 2 +- .../interaction/runtime/selector-read.ts | 6 ++++ src/core/command-descriptor/registry.ts | 12 +++++++ src/core/dispatch.ts | 3 ++ src/core/lease-scope.ts | 3 ++ src/core/platform-plugin/plugin.ts | 5 ++- src/daemon/__tests__/lease-context.test.ts | 2 +- .../session-replay-target-guard.test.ts | 5 ++- src/daemon/lease-context.ts | 8 +---- src/kernel/device.ts | 3 ++ src/platforms/android/ime-helper.ts | 3 ++ src/platforms/android/ime-lifecycle.ts | 6 ++++ .../android/snapshot-helper-install.ts | 4 ++- .../android/snapshot-helper-session.ts | 4 ++- .../core/runner/runner-recycle-ledger.ts | 4 ++- .../apple/core/runner/runner-transport.ts | 4 ++- src/platforms/install-source.ts | 3 ++ src/platforms/linux/linux-env.ts | 4 ++- src/provider-device-runtime.ts | 3 ++ src/utils/ttl-memo.ts | 4 +++ .../native-ref.contract.test.ts | 2 +- ...ution-disclosure-mutation.contract.test.ts | 2 +- .../runtime-ref.contract.test.ts | 2 +- .../runtime-selector.contract.test.ts | 2 +- 37 files changed, 110 insertions(+), 62 deletions(-) diff --git a/fallow-baselines/production-unused-exports.json b/fallow-baselines/production-unused-exports.json index db04817fa5..5cb772bde5 100644 --- a/fallow-baselines/production-unused-exports.json +++ b/fallow-baselines/production-unused-exports.json @@ -1,40 +1,6 @@ { "unused_files": [], - "unused_exports": [ - "src/cli/parser/args.ts:parseArgs", - "src/cli/parser/command-suggestions.ts:listCommandAliasSuggestionEntries", - "src/cloud-webdriver/aws-device-farm.ts:getAwsDeviceFarmWebDriverCapabilities", - "src/cloud-webdriver/aws-device-farm.ts:createAwsDeviceFarmWebDriverRuntime", - "src/cloud-webdriver/browserstack.ts:getBrowserStackWebDriverCapabilities", - "src/cloud-webdriver/browserstack.ts:createBrowserStackWebDriverRuntime", - "src/commands/command-metadata.ts:listCommandMetadataNames", - "src/commands/command-surface.ts:listExecutableCommandNames", - "src/commands/index.ts:ref", - "src/commands/index.ts:selector", - "src/commands/index.ts:commands", - "src/commands/interaction/runtime/selector-read.ts:selector", - "src/commands/interaction/runtime/selector-read.ts:ref", - "src/core/command-descriptor/registry.ts:listDescriptorCatalogCommandNames", - "src/core/command-descriptor/registry.ts:listDescriptorDispatchCommandNames", - "src/core/command-descriptor/registry.ts:listCapabilityCheckedCommandNames", - "src/core/command-descriptor/registry.ts:listCommandResponseDataTransforms", - "src/core/dispatch.ts:listRegisteredDispatchCommandNames", - "src/core/platform-plugin/plugin.ts:registeredPlatforms", - "src/daemon/lease-context.ts:buildLeaseDiagnosticsContext", - "src/kernel/device.ts:isPlatform", - "src/platforms/android/ime-helper.ts:resetAndroidImeHelperInstallCache", - "src/platforms/android/ime-lifecycle.ts:resetAndroidTestImeActivationCacheForTests", - "src/platforms/android/ime-lifecycle.ts:setAndroidTestImeActiveForTests", - "src/platforms/android/multitouch-helper.ts:resetAndroidMultiTouchHelperInstallCache", - "src/platforms/android/snapshot-helper-install.ts:resetAndroidSnapshotHelperInstallCache", - "src/platforms/android/snapshot-helper-session.ts:resetAndroidSnapshotHelperSessions", - "src/platforms/apple/core/runner/runner-recycle-ledger.ts:resetRunnerRecycleLedgerForTests", - "src/platforms/apple/core/runner/runner-transport.ts:clearDeviceTunnelIpCache", - "src/platforms/install-source.ts:ARCHIVE_EXTENSIONS", - "src/platforms/linux/linux-env.ts:resetInputToolCache", - "src/provider-device-runtime.ts:setActiveProviderDeviceRuntimes", - "src/utils/ttl-memo.ts:resetAllProcessMemosForTests" - ], + "unused_exports": [], "unused_types": [], "private_type_leaks": [], "unused_dependencies": [], diff --git a/src/cli/parser/args.ts b/src/cli/parser/args.ts index 6eae61691a..d5eed4c9f1 100644 --- a/src/cli/parser/args.ts +++ b/src/cli/parser/args.ts @@ -38,6 +38,9 @@ type FinalizeArgsOptions = ParseArgsOptions & { defaultFlags?: Partial; }; +/** + * @internal High-level argv parser used by unit tests and build scripts. + */ export function parseArgs(argv: string[], options?: FinalizeArgsOptions): ParsedArgs { return finalizeParsedArgs(parseRawArgs(argv), options); } diff --git a/src/cli/parser/command-suggestions.ts b/src/cli/parser/command-suggestions.ts index 132dd7900d..cdaf752cbc 100644 --- a/src/cli/parser/command-suggestions.ts +++ b/src/cli/parser/command-suggestions.ts @@ -43,6 +43,9 @@ const COMMAND_ALIAS_SUGGESTIONS: Record = { 'close-session': { command: 'close', example: 'close' }, }; +/** + * @internal Exposes the curated suggestion map for drift/parity tests. + */ export function listCommandAliasSuggestionEntries(): Array<[string, CommandAliasSuggestion]> { return Object.entries(COMMAND_ALIAS_SUGGESTIONS); } diff --git a/src/cloud-webdriver/aws-device-farm.ts b/src/cloud-webdriver/aws-device-farm.ts index e88652d38e..83f129be21 100644 --- a/src/cloud-webdriver/aws-device-farm.ts +++ b/src/cloud-webdriver/aws-device-farm.ts @@ -100,6 +100,9 @@ export type AwsDeviceFarmWebDriverRuntimeOptions = { prepareSession?: CloudWebDriverRuntimeOptions['prepareSession']; }; +/** + * @internal AWS Device Farm capability builder used by integration tests. + */ export function getAwsDeviceFarmWebDriverCapabilities( platform: CloudWebDriverPlatform, ): CloudWebDriverProviderCapabilities { @@ -110,6 +113,9 @@ export function getAwsDeviceFarmWebDriverCapabilities( }); } +/** + * @internal AWS Device Farm runtime factory used by integration tests. + */ export function createAwsDeviceFarmWebDriverRuntime( options: AwsDeviceFarmWebDriverRuntimeOptions, ): ProviderDeviceRuntime { diff --git a/src/cloud-webdriver/browserstack.ts b/src/cloud-webdriver/browserstack.ts index b3f89bf0c4..6d41ac1dad 100644 --- a/src/cloud-webdriver/browserstack.ts +++ b/src/cloud-webdriver/browserstack.ts @@ -77,6 +77,9 @@ export type BrowserStackCapabilitiesOptions = { configured?: Record; }; +/** + * @internal BrowserStack capability builder used by integration tests. + */ export function getBrowserStackWebDriverCapabilities( platform: CloudWebDriverPlatform, ): CloudWebDriverProviderCapabilities { @@ -87,6 +90,9 @@ export function getBrowserStackWebDriverCapabilities( }); } +/** + * @internal BrowserStack runtime factory used by integration tests. + */ export function createBrowserStackWebDriverRuntime( options: BrowserStackWebDriverRuntimeOptions, ): ProviderDeviceRuntime { diff --git a/src/commands/command-metadata.ts b/src/commands/command-metadata.ts index e78c52f975..1930e50daa 100644 --- a/src/commands/command-metadata.ts +++ b/src/commands/command-metadata.ts @@ -26,6 +26,9 @@ export function listMcpCommandMetadata(): AnyCommandMetadata[] { }); } +/** + * @internal Introspection helper used by command surface parity tests. + */ export function listCommandMetadataNames(): CommandName[] { return [...commandMetadataMap.keys()].sort(); } diff --git a/src/commands/command-surface.ts b/src/commands/command-surface.ts index eeedeb235f..b7bfb00a02 100644 --- a/src/commands/command-surface.ts +++ b/src/commands/command-surface.ts @@ -19,6 +19,9 @@ export async function runCommand( return await getCommandDefinition(name).invoke(client, input); } +/** + * @internal Introspection helper used by command surface parity tests. + */ export function listExecutableCommandNames(): CommandName[] { return [...commandMap.keys()].sort(); } diff --git a/src/commands/index.ts b/src/commands/index.ts index d2c988d260..4a48ef689c 100644 --- a/src/commands/index.ts +++ b/src/commands/index.ts @@ -44,8 +44,6 @@ import { type SystemCommands, } from './system/runtime/index.ts'; -export { ref, selector } from './interaction/runtime/selector-read.ts'; - export type { BoundRuntimeCommand, CommandResult, @@ -77,6 +75,9 @@ export type BoundAgentDeviceCommands = { observability: BoundObservabilityCommands; }; +/** + * @internal Runtime command catalog used by parity/type tests. + */ export const commands: AgentDeviceCommands = { capture: captureCommands, selectors: selectorCommands, diff --git a/src/commands/interaction/runtime/__tests__/test-utils/index.ts b/src/commands/interaction/runtime/__tests__/test-utils/index.ts index aa5e9ab9de..be8776f83c 100644 --- a/src/commands/interaction/runtime/__tests__/test-utils/index.ts +++ b/src/commands/interaction/runtime/__tests__/test-utils/index.ts @@ -7,7 +7,7 @@ import { localCommandPolicy, type CommandSessionStore, } from '../../../../../runtime.ts'; -import { ref } from '../../../../index.ts'; +import { ref } from '../../selector-read.ts'; import { makeSnapshotState } from '../../../../../__tests__/test-utils/index.ts'; export function selectorSnapshot(): SnapshotState { diff --git a/src/commands/interaction/runtime/gestures.test.ts b/src/commands/interaction/runtime/gestures.test.ts index 11a1785481..3b95e8460a 100644 --- a/src/commands/interaction/runtime/gestures.test.ts +++ b/src/commands/interaction/runtime/gestures.test.ts @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; -import { ref, selector } from '../../index.ts'; +import { ref, selector } from './selector-read.ts'; import { AppError } from '../../../kernel/errors.ts'; import { createInteractionDevice, diff --git a/src/commands/interaction/runtime/index.test.ts b/src/commands/interaction/runtime/index.test.ts index eec255cc03..1b4060fdbf 100644 --- a/src/commands/interaction/runtime/index.test.ts +++ b/src/commands/interaction/runtime/index.test.ts @@ -1,6 +1,7 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; -import { commands, selector } from '../../index.ts'; +import { commands } from '../../index.ts'; +import { selector } from './selector-read.ts'; import { createInteractionDevice, selectorSnapshot } from './__tests__/test-utils/index.ts'; test('runtime interaction commands are available from the command namespace', async () => { diff --git a/src/commands/interaction/runtime/interactions.test.ts b/src/commands/interaction/runtime/interactions.test.ts index 61a337900d..07beaece6b 100644 --- a/src/commands/interaction/runtime/interactions.test.ts +++ b/src/commands/interaction/runtime/interactions.test.ts @@ -1,7 +1,7 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; import type { AgentDeviceBackend } from '../../../backend.ts'; -import { ref, selector } from '../../index.ts'; +import { ref, selector } from './selector-read.ts'; import { createLocalArtifactAdapter } from '../../../io.ts'; import { createAgentDevice, diff --git a/src/commands/interaction/runtime/resolution.test.ts b/src/commands/interaction/runtime/resolution.test.ts index 72e60e9c14..41cd8b00a4 100644 --- a/src/commands/interaction/runtime/resolution.test.ts +++ b/src/commands/interaction/runtime/resolution.test.ts @@ -1,7 +1,7 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; import type { BackendSnapshotOptions } from '../../../backend.ts'; -import { ref, selector } from '../../index.ts'; +import { ref, selector } from './selector-read.ts'; import { resolveActionableTouchResolution } from '../../../core/interaction-targeting.ts'; import { tryResolveRefNode } from './resolution.ts'; import { makeSnapshotState } from '../../../__tests__/test-utils/index.ts'; diff --git a/src/commands/interaction/runtime/selector-read.test.ts b/src/commands/interaction/runtime/selector-read.test.ts index d5a530ce95..3f8e4071bb 100644 --- a/src/commands/interaction/runtime/selector-read.test.ts +++ b/src/commands/interaction/runtime/selector-read.test.ts @@ -8,7 +8,7 @@ import { localCommandPolicy, type CommandSessionStore, } from '../../../runtime.ts'; -import { ref, selector } from '../../index.ts'; +import { ref, selector } from './selector-read.ts'; import { makeSnapshotState } from '../../../__tests__/test-utils/index.ts'; import { createSelectorDevice, selectorReadSnapshot } from './__tests__/test-utils/index.ts'; diff --git a/src/commands/interaction/runtime/selector-read.ts b/src/commands/interaction/runtime/selector-read.ts index a7d6696ee3..b6f939a23c 100644 --- a/src/commands/interaction/runtime/selector-read.ts +++ b/src/commands/interaction/runtime/selector-read.ts @@ -152,10 +152,16 @@ export type IsSelectorCommandOptions = CommandContext & target: SelectorTarget; }; +/** + * @internal Target helper used by tests/examples; runtime callers compose `ElementTarget` directly. + */ export function selector(expression: string): SelectorTarget { return { kind: 'selector', selector: expression }; } +/** + * @internal Target helper used by tests/examples; runtime callers compose `ElementTarget` directly. + */ export function ref(refInput: string, options: { fallbackLabel?: string } = {}): RefTarget { return { kind: 'ref', diff --git a/src/core/command-descriptor/registry.ts b/src/core/command-descriptor/registry.ts index 91787990ca..33f973ead3 100644 --- a/src/core/command-descriptor/registry.ts +++ b/src/core/command-descriptor/registry.ts @@ -1159,6 +1159,9 @@ export const commandDescriptors = RAW_COMMAND_DESCRIPTORS.map((descriptor) => { /** The literal union of every registered command name. */ export type Command = (typeof commandDescriptors)[number]['name']; +/** + * @internal Introspection helper used by parity tests. + */ export function listDescriptorCatalogCommandNames( group: Group, ): Array> { @@ -1181,6 +1184,9 @@ export function listDescriptorCatalogEntries( ); } +/** + * @internal Introspection helper used by parity tests. + */ export function listDescriptorDispatchCommandNames(): DescriptorDispatchCommandName[] { return commandDescriptors .filter((descriptor) => 'dispatch' in descriptor && descriptor.dispatch !== undefined) @@ -1195,6 +1201,9 @@ export function listMcpExposedCommandNames(): DescriptorCliCommandName[] { .sort(); } +/** + * @internal Introspection helper used by parity tests. + */ export function listCapabilityCheckedCommandNames(): DescriptorCliCommandName[] { return commandDescriptors .filter((descriptor) => isCapabilityCheckedCliCommand(descriptor)) @@ -1282,6 +1291,9 @@ export function resolveCommandResponseDataTransform( return RESPONSE_DATA_TRANSFORM_BY_COMMAND.get(command); } +/** + * @internal Introspection helper used by parity tests. + */ export function listCommandResponseDataTransforms(): Array<{ command: string; transform: CommandResponseDataTransform; diff --git a/src/core/dispatch.ts b/src/core/dispatch.ts index f9c3ff69ac..02add1da83 100644 --- a/src/core/dispatch.ts +++ b/src/core/dispatch.ts @@ -188,6 +188,9 @@ const DISPATCH_HANDLERS: Record = { read: ({ device, positionals, context }) => handleReadCommand(device, positionals, context), }; +/** + * @internal Introspection helper used by parity tests. + */ export function listRegisteredDispatchCommandNames(): string[] { return Object.keys(DISPATCH_HANDLERS).sort(); } diff --git a/src/core/lease-scope.ts b/src/core/lease-scope.ts index 48f5bd2eef..acd33de2a9 100644 --- a/src/core/lease-scope.ts +++ b/src/core/lease-scope.ts @@ -208,6 +208,9 @@ export function leaseScopeToConnectionMetadata( return Object.keys(connection).length > 0 ? connection : undefined; } +/** + * @internal Lease diagnostics seam exposed for unit tests. + */ export function buildLeaseDiagnosticsContext( leaseScope: LeaseScope | undefined, ): LeaseDiagnosticsContext | undefined { diff --git a/src/core/platform-plugin/plugin.ts b/src/core/platform-plugin/plugin.ts index a43924e0b6..f8749dfaee 100644 --- a/src/core/platform-plugin/plugin.ts +++ b/src/core/platform-plugin/plugin.ts @@ -185,7 +185,10 @@ export function tryGetPlugin(platform: Platform): PlatformPlugin | undefined { return registry.get(platform); } -/** The leaf platforms that currently carry a plugin, in registration order. */ +/** + * @internal The leaf platforms that currently carry a plugin, in registration order. + * Exposed for parity tests. + */ export function registeredPlatforms(): Platform[] { return [...registry.keys()]; } diff --git a/src/daemon/__tests__/lease-context.test.ts b/src/daemon/__tests__/lease-context.test.ts index c90a91793c..20b53a34e0 100644 --- a/src/daemon/__tests__/lease-context.test.ts +++ b/src/daemon/__tests__/lease-context.test.ts @@ -1,12 +1,12 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; import { - buildLeaseDiagnosticsContext, buildSessionLeaseFromRequest, resolveRunnerLogicalLeaseContext, resolveRequestOrSessionLeaseScope, type SessionLease, } from '../lease-context.ts'; +import { buildLeaseDiagnosticsContext } from '../../core/lease-scope.ts'; import type { DaemonRequest } from '../types.ts'; test('buildSessionLeaseFromRequest captures complete request lease scope', () => { diff --git a/src/daemon/handlers/__tests__/session-replay-target-guard.test.ts b/src/daemon/handlers/__tests__/session-replay-target-guard.test.ts index 93d398c7a8..fba087f508 100644 --- a/src/daemon/handlers/__tests__/session-replay-target-guard.test.ts +++ b/src/daemon/handlers/__tests__/session-replay-target-guard.test.ts @@ -13,7 +13,10 @@ import { type ReplayTargetGuardDenotation, } from '../../../replay/target-identity-node.ts'; import { makeSnapshotState } from '../../../__tests__/test-utils/index.ts'; -import { ref as interactionRef, selector } from '../../../commands/index.ts'; +import { + ref as interactionRef, + selector, +} from '../../../commands/interaction/runtime/selector-read.ts'; import { createInteractionDevice } from '../../../commands/interaction/runtime/__tests__/test-utils/index.ts'; import { classifyReplayTarget } from '../session-replay-target-classification.ts'; diff --git a/src/daemon/lease-context.ts b/src/daemon/lease-context.ts index a75ce38e09..2928694faf 100644 --- a/src/daemon/lease-context.ts +++ b/src/daemon/lease-context.ts @@ -5,7 +5,6 @@ import type { RunnerLogicalLeaseContext } from '../core/runner-lease-context.ts' import { stripUndefined } from '../utils/parsing.ts'; import { DEFAULT_PROXY_LEASE_TTL_MS, - buildLeaseDiagnosticsContext, findMissingProxyLeaseFields, isProxyLeaseScope, leaseScopeFromRequest, @@ -13,12 +12,7 @@ import { type LeaseScope, } from '../core/lease-scope.ts'; -export { - DEFAULT_PROXY_LEASE_TTL_MS, - buildLeaseDiagnosticsContext, - findMissingProxyLeaseFields, - isProxyLeaseScope, -}; +export { DEFAULT_PROXY_LEASE_TTL_MS, findMissingProxyLeaseFields, isProxyLeaseScope }; export type { LeaseDiagnosticsContext, LeaseScope }; export type SessionLease = { diff --git a/src/kernel/device.ts b/src/kernel/device.ts index 782c62e8f9..bb2dea2dc0 100644 --- a/src/kernel/device.ts +++ b/src/kernel/device.ts @@ -142,6 +142,9 @@ export function resolveDeviceAppleOs( return 'ios'; } +/** + * @internal Public type guard exposed for unit tests. + */ export function isPlatform(value: unknown): value is Platform { // Internal device-platform membership derived from the canonical PLATFORMS tuple. return (PLATFORMS as readonly unknown[]).includes(value); diff --git a/src/platforms/android/ime-helper.ts b/src/platforms/android/ime-helper.ts index 3d94c5a69e..531df3a1f2 100644 --- a/src/platforms/android/ime-helper.ts +++ b/src/platforms/android/ime-helper.ts @@ -110,6 +110,9 @@ export const ensureAndroidImeHelper = makeEnsureAndroidHelperInstalled { } } +/** + * @internal Test isolation hook for the active test-IME device set. + */ export function resetAndroidTestImeActivationCacheForTests(): void { activeTestImeDevices.clear(); } +/** + * @internal Test seam to force the active test-IME state for a device. + */ export function setAndroidTestImeActiveForTests(device: DeviceInfo, active: boolean): void { const key = getAndroidImeHelperDeviceKey(device); if (active) { diff --git a/src/platforms/android/snapshot-helper-install.ts b/src/platforms/android/snapshot-helper-install.ts index 823b4de9a9..9329a6aba4 100644 --- a/src/platforms/android/snapshot-helper-install.ts +++ b/src/platforms/android/snapshot-helper-install.ts @@ -29,7 +29,9 @@ export function forgetAndroidSnapshotHelperInstall(options: { } } -// Tests reset the process-global install memo so cases do not share helper state. +/** + * @internal Test isolation hook for process-global snapshot helper install cache. + */ export function resetAndroidSnapshotHelperInstallCache(): void { installedSnapshotHelpers.clear(); } diff --git a/src/platforms/android/snapshot-helper-session.ts b/src/platforms/android/snapshot-helper-session.ts index e83d960b1e..ac256793c2 100644 --- a/src/platforms/android/snapshot-helper-session.ts +++ b/src/platforms/android/snapshot-helper-session.ts @@ -148,7 +148,9 @@ export function resolveAndroidSnapshotHelperSessionRequestTimeoutMs(params: { ); } -// Tests stop persistent helper processes so cases cannot leak sessions into each other. +/** + * @internal Test isolation hook for persistent snapshot helper sessions. + */ export async function resetAndroidSnapshotHelperSessions(): Promise { await Promise.all( [...sessions.keys()].map((deviceKey) => stopAndroidSnapshotHelperSession(deviceKey)), diff --git a/src/platforms/apple/core/runner/runner-recycle-ledger.ts b/src/platforms/apple/core/runner/runner-recycle-ledger.ts index 6bfb6394df..1499baaab7 100644 --- a/src/platforms/apple/core/runner/runner-recycle-ledger.ts +++ b/src/platforms/apple/core/runner/runner-recycle-ledger.ts @@ -98,7 +98,9 @@ export function buildRunnerRecycleBudgetExhaustedError( ); } -// Test isolation requires clearing process-global recycle accounting between cases. +/** + * @internal Test isolation hook for process-global runner recycle accounting. + */ export function resetRunnerRecycleLedgerForTests(): void { ledger.clear(); } diff --git a/src/platforms/apple/core/runner/runner-transport.ts b/src/platforms/apple/core/runner/runner-transport.ts index 6d67a9d8f9..8f1a0f529f 100644 --- a/src/platforms/apple/core/runner/runner-transport.ts +++ b/src/platforms/apple/core/runner/runner-transport.ts @@ -423,7 +423,9 @@ function invalidateDeviceTunnelIpCache(deviceId: string): void { deviceTunnelIpCache.delete(deviceId); } -// Test isolation requires clearing the process-global device tunnel cache between cases. +/** + * @internal Test isolation hook for the process-global device tunnel IP cache. + */ export function clearDeviceTunnelIpCache(): void { deviceTunnelIpCache.clear(); } diff --git a/src/platforms/install-source.ts b/src/platforms/install-source.ts index 601bc2d4e0..ffcaf33e14 100644 --- a/src/platforms/install-source.ts +++ b/src/platforms/install-source.ts @@ -45,6 +45,9 @@ export type MaterializedInstallable = { const INTERNAL_ARCHIVE_EXTENSIONS = ['.zip', '.tar', '.tar.gz', '.tgz'] as const; +/** + * @public Archive extensions accepted by install-source resolution. + */ export const ARCHIVE_EXTENSIONS = Object.freeze([...INTERNAL_ARCHIVE_EXTENSIONS] as const); const MAX_INSTALL_SOURCE_SEARCH_DEPTH = 5; const DEFAULT_SOURCE_DOWNLOAD_TIMEOUT_MS = 120_000; diff --git a/src/platforms/linux/linux-env.ts b/src/platforms/linux/linux-env.ts index ae2fb17efa..edfebcef8c 100644 --- a/src/platforms/linux/linux-env.ts +++ b/src/platforms/linux/linux-env.ts @@ -55,7 +55,9 @@ export async function ensureInputTool(): Promise<{ ); } -/** Reset cached tool (for testing). */ +/** + * @internal Test isolation hook for the cached Linux input tool. + */ export function resetInputToolCache(): void { cachedInputTool = null; } diff --git a/src/provider-device-runtime.ts b/src/provider-device-runtime.ts index 52de51dd09..bf6c06f7c6 100644 --- a/src/provider-device-runtime.ts +++ b/src/provider-device-runtime.ts @@ -69,6 +69,9 @@ export type ProviderDeviceRuntimeRequestProviders = { let activeProviderDeviceRuntimes: ProviderDeviceRuntime[] = []; const providerDeviceRuntimeScope = new AsyncLocalStorage(); +/** + * @internal Test isolation hook for the active provider runtime scope. + */ export function setActiveProviderDeviceRuntimes(runtimes: ProviderDeviceRuntime[]): void { activeProviderDeviceRuntimes = [...runtimes]; } diff --git a/src/utils/ttl-memo.ts b/src/utils/ttl-memo.ts index 059eb178a3..7599a91332 100644 --- a/src/utils/ttl-memo.ts +++ b/src/utils/ttl-memo.ts @@ -74,6 +74,10 @@ export function createTtlMemo(options: TtlMemoOptions = {}): TtlMemo return memo; } +/** + * Test isolation hook for process-global TTL memos. + * @internal + */ export function resetAllProcessMemosForTests(): void { for (const reset of processMemoResets) { reset(); diff --git a/test/integration/interaction-contract/native-ref.contract.test.ts b/test/integration/interaction-contract/native-ref.contract.test.ts index 6d0fb21607..ecd75591aa 100644 --- a/test/integration/interaction-contract/native-ref.contract.test.ts +++ b/test/integration/interaction-contract/native-ref.contract.test.ts @@ -2,7 +2,7 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; import type { InteractionGuarantee } from '../../../src/contracts/interaction-guarantees.ts'; import type { SnapshotState } from '../../../src/kernel/snapshot.ts'; -import { ref } from '../../../src/commands/index.ts'; +import { ref } from '../../../src/commands/interaction/runtime/selector-read.ts'; import { scenarioName } from './coverage-manifest.ts'; import { buildInteractionResponseData } from '../../../src/daemon/handlers/interaction-touch-response.ts'; import { NATIVE_REF_COVERAGE } from './native-ref.coverage.ts'; diff --git a/test/integration/interaction-contract/resolution-disclosure-mutation.contract.test.ts b/test/integration/interaction-contract/resolution-disclosure-mutation.contract.test.ts index 3ee0e8f45d..fbaefe565c 100644 --- a/test/integration/interaction-contract/resolution-disclosure-mutation.contract.test.ts +++ b/test/integration/interaction-contract/resolution-disclosure-mutation.contract.test.ts @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; -import { ref, selector } from '../../../src/commands/index.ts'; +import { ref, selector } from '../../../src/commands/interaction/runtime/selector-read.ts'; import { drawerWithVisibleTwinSnapshot } from './fixtures.ts'; import { createContractDevice } from './runtime-harness.ts'; diff --git a/test/integration/interaction-contract/runtime-ref.contract.test.ts b/test/integration/interaction-contract/runtime-ref.contract.test.ts index f252388e62..e430913461 100644 --- a/test/integration/interaction-contract/runtime-ref.contract.test.ts +++ b/test/integration/interaction-contract/runtime-ref.contract.test.ts @@ -2,7 +2,7 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; import type { InteractionGuarantee } from '../../../src/contracts/interaction-guarantees.ts'; import type { Point } from '../../../src/kernel/snapshot.ts'; -import { ref } from '../../../src/commands/index.ts'; +import { ref } from '../../../src/commands/interaction/runtime/selector-read.ts'; import { assertRpcOk } from '../provider-scenarios/assertions.ts'; import { scenarioName, scenarioNames } from './coverage-manifest.ts'; import { RUNTIME_REF_COVERAGE } from './runtime-ref.coverage.ts'; diff --git a/test/integration/interaction-contract/runtime-selector.contract.test.ts b/test/integration/interaction-contract/runtime-selector.contract.test.ts index 1e28b8401d..69bb59bfde 100644 --- a/test/integration/interaction-contract/runtime-selector.contract.test.ts +++ b/test/integration/interaction-contract/runtime-selector.contract.test.ts @@ -2,7 +2,7 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; import type { InteractionGuarantee } from '../../../src/contracts/interaction-guarantees.ts'; import type { Point } from '../../../src/kernel/snapshot.ts'; -import { selector } from '../../../src/commands/index.ts'; +import { selector } from '../../../src/commands/interaction/runtime/selector-read.ts'; import { assertRpcOk } from '../provider-scenarios/assertions.ts'; import { scenarioName, scenarioNames } from './coverage-manifest.ts'; import { RUNTIME_SELECTOR_COVERAGE } from './runtime-selector.coverage.ts'; From f06b1882592e6973cd9df64e416d125b4970763e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 16 Jul 2026 09:02:02 +0000 Subject: [PATCH 2/3] chore: address review feedback on production-exports cleanup (#1276) - CONTRIBUTING.md: document that intentional non-production exports should use JSDoc @internal with a short justification, treated as a reviewed baseline entry. - isPlatform: fix JSDoc tag to "@internal" and remove conflicting "public" wording. - ARCHIVE_EXTENSIONS: re-export from src/sdk/install-source.ts so the public install-source subpath has a real consumer story for the constant. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- CONTRIBUTING.md | 4 ++-- src/kernel/device.ts | 2 +- src/sdk/install-source.ts | 1 + 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ba7d4deb1..ac6b239bf2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,8 +65,8 @@ same-file consumer out of this report without weakening the general Fallow audit native baseline lives at `fallow-baselines/production-unused-exports.json`. Fix a finding by wiring the export into production or removing the unnecessary export/code. For -an intentional test seam, explain why beside the declaration and keep the reviewed entry in the -production-export baseline. An inline +an intentional test seam or other non-production consumer, add a JSDoc `@internal` tag with a short +justification beside the declaration and treat it as a reviewed baseline entry. An inline `// fallow-ignore-next-line unused-export` is not suitable here: the general test-inclusive graph sees the test consumer and correctly reports that suppression as stale. Run `pnpm check:production-exports:baseline` only for a deliberate reviewed baseline migration or to diff --git a/src/kernel/device.ts b/src/kernel/device.ts index bb2dea2dc0..3c9c3db927 100644 --- a/src/kernel/device.ts +++ b/src/kernel/device.ts @@ -143,7 +143,7 @@ export function resolveDeviceAppleOs( } /** - * @internal Public type guard exposed for unit tests. + * @internal Type guard exposed for unit tests. */ export function isPlatform(value: unknown): value is Platform { // Internal device-platform membership derived from the canonical PLATFORMS tuple. diff --git a/src/sdk/install-source.ts b/src/sdk/install-source.ts index 5f40d186c4..2b732f9512 100644 --- a/src/sdk/install-source.ts +++ b/src/sdk/install-source.ts @@ -1,4 +1,5 @@ export { + ARCHIVE_EXTENSIONS, isTrustedInstallSourceUrl, validateDownloadSourceUrl, } from '../platforms/install-source.ts'; From 49e9ff010f34af7faa82c145d4084b818ce94c65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 16 Jul 2026 09:15:47 +0000 Subject: [PATCH 3/3] chore: make production-exports check truly baseline-free (#1276) - Drop --baseline from pnpm check:production-exports and remove the check:production-exports:baseline generation script. - Delete fallow-baselines/production-unused-exports.json. - Update CONTRIBUTING.md to describe the baseline-free behavior and remove references to reviewed baseline entries for production unused exports. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- CONTRIBUTING.md | 18 ++++++------ .../production-unused-exports.json | 28 ------------------- package.json | 3 +- 3 files changed, 9 insertions(+), 40 deletions(-) delete mode 100644 fallow-baselines/production-unused-exports.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac6b239bf2..737d36cccb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,21 +59,19 @@ intentionally accepting a finding. Code quality (production exports): `pnpm check:production-exports` runs Fallow's native production graph, which excludes test/story/dev files, and fails when a new export has no production consumer. This includes the test-only-export bug class that shipped in #1199's first -revision, while also catching exports that are unreachable from every graph. Fallow's +revision, while also catching exports that are unreachable from every graph. It is intentionally +baseline-free: there is no grandfather file, so a new unused production export fails loudly. Fallow's `ignoreExportsUsedInFile` option in the gate's inherited config keeps exports with a real -same-file consumer out of this report without weakening the general Fallow audit. The checked-in -native baseline lives at `fallow-baselines/production-unused-exports.json`. +same-file consumer out of this report without weakening the general Fallow audit. Fix a finding by wiring the export into production or removing the unnecessary export/code. For an intentional test seam or other non-production consumer, add a JSDoc `@internal` tag with a short -justification beside the declaration and treat it as a reviewed baseline entry. An inline +justification beside the declaration. An inline `// fallow-ignore-next-line unused-export` is not suitable here: the general test-inclusive graph -sees the test consumer and correctly reports that suppression as stale. Run -`pnpm check:production-exports:baseline` only for a deliberate reviewed baseline migration or to -remove stale entries; additions accept new production-unreachable exports and should be rare. -Production usage reached only through dynamic property access remains invisible to a static -import graph, so register those exports in `.fallowrc.json` `ignoreExports` instead (as with the -daemon route handlers loaded through `typeof import()`). +sees the test consumer and correctly reports that suppression as stale. Production usage reached +only through dynamic property access remains invisible to a static import graph, so register those +exports in `.fallowrc.json` `ignoreExports` instead (as with the daemon route handlers loaded +through `typeof import()`). Optional device selectors for tests: diff --git a/fallow-baselines/production-unused-exports.json b/fallow-baselines/production-unused-exports.json deleted file mode 100644 index 5cb772bde5..0000000000 --- a/fallow-baselines/production-unused-exports.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "unused_files": [], - "unused_exports": [], - "unused_types": [], - "private_type_leaks": [], - "unused_dependencies": [], - "unused_dev_dependencies": [], - "circular_dependencies": [], - "re_export_cycles": [], - "unused_optional_dependencies": [], - "unused_enum_members": [], - "unused_class_members": [], - "unresolved_imports": [], - "unlisted_dependencies": [], - "duplicate_exports": [], - "type_only_dependencies": [], - "test_only_dependencies": [], - "boundary_violations": [], - "boundary_coverage_violations": [], - "boundary_call_violations": [], - "policy_violations": [], - "stale_suppressions": [], - "unused_catalog_entries": [], - "empty_catalog_groups": [], - "unresolved_catalog_references": [], - "unused_dependency_overrides": [], - "misconfigured_dependency_overrides": [] -} diff --git a/package.json b/package.json index 422fa7cc08..d5e95e3003 100644 --- a/package.json +++ b/package.json @@ -119,8 +119,7 @@ "check:affected": "node --experimental-strip-types scripts/check-affected/run.ts", "check:affected:test": "node --experimental-strip-types --test scripts/check-affected/model.test.ts scripts/check-affected/run.test.ts", "check:layering": "node --experimental-strip-types --test scripts/layering/model.test.ts && node --experimental-strip-types scripts/layering/check.ts", - "check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --baseline fallow-baselines/production-unused-exports.json --fail-on-issues", - "check:production-exports:baseline": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --save-baseline fallow-baselines/production-unused-exports.json --summary", + "check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues", "check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts", "check:quick": "pnpm lint && pnpm typecheck", "sync:mcp-metadata": "node scripts/sync-mcp-metadata.mjs",