perf(package): strip comments from the Apple runner source the npm package ships (#2467)

* perf(package): strip comments from the Apple runner source the npm package ships

The packager copies apple/runner/** into dist/ as Swift source, removing only
its AGENT_DEVICE_RUNNER_UNIT_TESTS blocks, so doc comments and design notes were
downloaded on every install: 71.9 kB of 441.2 kB of packaged runner Swift.

Add a lexical scanner for the removal. A regex cannot do this: `//` and `/*`
open a comment only in code position, raw literals move their own delimiter and
escape with the `#` count, interpolation segments hold code and further
literals, and Swift block comments nest. A construct the scanner cannot account
for throws at packaging time instead of shipping Swift that does not compile.

* fix(package): keep Swift regex literals out of the comment scanner

`#/foo//bar/#` is a valid extended regex literal with no comment in it, but the
scanner only knew the `#"` raw-string family, so it read the literal's `//` as a
line comment and shipped `let pattern = #/foo` — Swift that does not compile.
Add `#/…/#` and `##/…/##` as a literal context: matching `#` counts, the
single- and multi-line forms, Swift's own-line rule for a multi-line closing
delimiter, and the `\/` escape that keeps one from closing early.

Bare `/…/` literals stay unresolvable, because the same `/` opens a comment,
divides, and starts a regex literal, and only the parse separates them. Where
one could begin — an expression position whose `/` is not followed by a space,
a tab or `)` — packaging throws by file and line instead of rewriting bytes it
cannot prove are code. Divisions (`width/2`, `Double(3)/Double(4)`), the
recording scripts' shebang and `(/)` keep flowing through.

* fix(package): keep the packaged runner source on the checkout's line numbers

`dist/apple/runner/**` is the Swift a user's `xcodebuild` and the runner name a
file and line in (it lands in runner.log), so those numbers are only worth
reading if they point at the same line of `apple/runner/**`. Both rewriting
passes now empty the lines they remove instead of deleting them: comment removal
(889 lines, 889 B) and the pre-existing unit-test `#if` block strip, which was
moving everything below a block by up to 883 lines (3,737 lines, 3,737 B).

`dist/apple/runner/` 555,907 B -> 488,635 B (-67,272 B, -12.1%); its Swift alone
441,196 B -> 373,924 B (-15.2%). Parity costs 4,626 B of the 71,898 B the
previous head saved.

Nothing in the repo compiles the packaged source, so a mis-lex that failed to
throw would ship Swift that does not build and no gate would see it. Add
`pnpm check:packaged-runner-swift`: it packages into a throwaway root and asserts
line-count parity plus the line of every declaration each packaged file still
carries, then runs `swiftc -parse` over all 44 files. The parse half reports
itself skipped where no Swift toolchain exists, so the gate is declared on the
macOS lane, where both halves run.

Author: thymikee

.github/workflows/macos.yml

@@ -70,6 +70,14 @@ jobs:
         uses: ./.github/actions/run-gate
         with: { gate: macos-coverage }
 
+      # The npm package ships apple/runner/** as rewritten Swift source, and nothing in the repo
+      # compiles the result — the first consumer is a user's xcodebuild. This lane is the only one
+      # with a Swift toolchain, so it is where `swiftc -parse` over the packaged files runs; the
+      # line-parity half of the same gate needs no toolchain. Seconds, no simulator (#2461).
+      - name: Check the packaged runner Swift parses and keeps its line numbering
+        uses: ./.github/actions/run-gate
+        with: { gate: packaged-runner-swift }
+
       - name: Run iOS snapshot Swift/TypeScript differential
         uses: ./.github/actions/run-gate
         with: { gate: ios-snapshot-differential }

package.json

@@ -156,14 +156,15 @@
     "check:daemon-wire-compat": "node --experimental-strip-types scripts/wire-compat/run.ts",
     "check:daemon-wire-compat:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/wire-compat/model.test.ts",
     "check:xctest-selection": "node --experimental-strip-types scripts/check-xctest-selection.ts",
+    "check:packaged-runner-swift": "node --experimental-strip-types scripts/check-packaged-runner-swift.ts",
     "check:tmpdir-leaks": "node --experimental-strip-types scripts/check-tmpdir-leaks.ts",
     "check:tmpdir-leaks:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/check-tmpdir-leaks-model.test.ts scripts/vitest-tmpdir-global-setup.test.ts scripts/node-test-tmpdir.test.ts scripts/swift-toolchain-tmpdir.test.ts",
     "check:freerange": "fr",
     "check:quick": "pnpm lint && pnpm typecheck",
     "sync:mcp-metadata": "node scripts/sync-mcp-metadata.mjs",
     "check:mcp-metadata": "node scripts/sync-mcp-metadata.mjs --check",
     "version": "pnpm sync:mcp-metadata && git add server.json",
-    "check:tooling": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm check:layering && pnpm depgraph:test && pnpm check:gate-manifest:test && pnpm check:gate-manifest && pnpm check:production-exports && pnpm check:tmpdir-leaks:test && pnpm check:xctest-selection && pnpm check:mcp-metadata && pnpm build && pnpm check:bundle-owner-files && pnpm check:package",
+    "check:tooling": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm check:layering && pnpm depgraph:test && pnpm check:gate-manifest:test && pnpm check:gate-manifest && pnpm check:production-exports && pnpm check:tmpdir-leaks:test && pnpm check:xctest-selection && pnpm check:packaged-runner-swift && pnpm check:mcp-metadata && pnpm build && pnpm check:bundle-owner-files && pnpm check:package",
     "check:unit": "pnpm test:unit && pnpm check:tmpdir-leaks && pnpm test:smoke",
     "check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
     "prepack": "pnpm check:mcp-metadata && pnpm package:npm",

scripts/__tests__/packaged-runner-swift.test.ts

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { declarationsByLine, parityFailures } from '../check-packaged-runner-swift.ts';
+
+function swift(...lines: string[]): string {
+  return `${lines.join('\n')}\n`;
+}
+
+const source = swift(
+  '// a design note',
+  'extension RunnerTests {',
+  '  /// What this does.',
+  '  func helper() -> Int { 1 }',
+  '}',
+);
+
+test('a packaged file that emptied its comment lines reports no failure', () => {
+  const packaged = swift('', 'extension RunnerTests {', '', '  func helper() -> Int { 1 }', '}');
+
+  assert.deepEqual(parityFailures('Fixture.swift', source, packaged), []);
+});
+
+test('a deleted comment line is named as a line-count failure', () => {
+  const packaged = swift('extension RunnerTests {', '  func helper() -> Int { 1 }', '}');
+
+  const failures = parityFailures('Fixture.swift', source, packaged);
+  assert.equal(failures.length, 1);
+  assert.match(failures[0] ?? '', /Fixture\.swift: packaged source has 4 lines, checkout has 6\./);
+  assert.match(failures[0] ?? '', /empty a removed line, not delete it/);
+});
+
+// The line count alone cannot see a rewrite that moves a declaration and pads elsewhere, which is
+// the failure an `xcodebuild` line number would land on.
+test('a declaration that moved while the line count held is named with its line', () => {
+  const packaged = swift('', 'extension RunnerTests {', '  func helper() -> Int { 1 }', '', '}');
+
+  const failures = parityFailures('Fixture.swift', source, packaged);
+  assert.equal(failures.length, 1);
+  assert.match(failures[0] ?? '', /Fixture\.swift:3: packaged `func helper`/);
+  assert.match(failures[0] ?? '', /is `\(blank\)` at the same line of the checkout/);
+});
+
+test('declarations are keyed by their one-based line', () => {
+  assert.deepEqual(
+    [
+      ...declarationsByLine(
+        swift('import XCTest', 'final class RunnerTests: XCTestCase {', '  func testCommand() {}'),
+      ),
+    ],
+    [
+      [2, 'class RunnerTests'],
+      [3, 'func testCommand'],
+    ],
+  );
+});