@invarn/cibuild 2.6.7 → 2.6.9

package/dist/src/commands/android-scanner.js

@@ -1,5 +1,6 @@
 import { resolve, relative } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { parseSettingsModules } from "../shared/gradle-settings.js";
 // ---------------------------------------------------------------------------
 // File discovery
 // ---------------------------------------------------------------------------
@@ -23,11 +24,22 @@ function findGradleFiles(root) {
         if (!existsSync(p))
             continue;
         const content = readFileSync(p, "utf-8");
-        // Matches: include ':module', include(":module"), include ':a', ':b'
-        const includeRe = /include\s*[\(']?\s*['"]:([^'")\s,]+)/g;
-        let m;
-        while ((m = includeRe.exec(content)) !== null) {
-            moduleDirs.add(m[1].replace(/:/g, "/"));
+        // One parser, shared with the detector. The regex that used to live here
+        // matched only the *first* argument of an `include`, so
+        // `include(":android", ":common", …)` — one call, eight modules in
+        // `SimonSchubert/LinuxCommandLibrary` — was read as one, and the module
+        // holding `jvmToolchain(21)` was never opened.
+        for (const mod of parseSettingsModules(content))
+            moduleDirs.add(mod);
+        // An included build is a Gradle project of its own, and a monorepo's
+        // convention plugins live in one. Its build file is where the Java level
+        // for every module it configures is often declared.
+        for (const included of parseIncludedBuilds(content)) {
+            for (const buildFile of ["build.gradle", "build.gradle.kts"]) {
+                const q = resolve(root, included, buildFile);
+                if (existsSync(q))
+                    candidates.push(q);
+            }
         }
     }
     for (const mod of moduleDirs) {
@@ -254,11 +266,16 @@ function extractKeystorePaths(content) {
  * Handles formats: "21", "17", "1.8" (→ 8), "VERSION_21", "VERSION_1_8" (→ 8).
  */
 function parseJavaVersion(raw) {
+    // `JvmTarget.fromTarget("17")` names the version inside a string.
+    const fromTarget = /fromTarget\s*\(\s*["']([^"']+)["']/.exec(raw);
+    if (fromTarget)
+        return parseJavaVersion(fromTarget[1]);
     // JavaVersion enum: VERSION_21, VERSION_17, VERSION_1_8
-    const enumMatch = /VERSION_1_(\d)$/.exec(raw);
+    // JvmTarget enum:   JVM_21, JVM_17, JVM_1_8
+    const enumMatch = /(?:VERSION|JVM)_1_(\d)$/.exec(raw);
     if (enumMatch)
         return parseInt(enumMatch[1], 10);
-    const enumMatch2 = /VERSION_(\d+)$/.exec(raw);
+    const enumMatch2 = /(?:VERSION|JVM)_(\d+)$/.exec(raw);
     if (enumMatch2)
         return parseInt(enumMatch2[1], 10);
     // String literal: "21", "17", "11", "1.8"
@@ -290,8 +307,21 @@ function detectJavaVersionInContent(content) {
         if (v)
             candidates.push(v);
     }
-    // jvmTarget = "21" (inside kotlinOptions or compileOptions)
-    const jvmTargetRe = /jvmTarget\s*=\s*["']([^"']+)["']/g;
+    // jvmTarget, in every form a Kotlin build writes it:
+    //   jvmTarget = "21"                          (kotlinOptions, Groovy)
+    //   jvmTarget.set(JvmTarget.JVM_17)           (compilerOptions, the form
+    //                                              LinuxCommandLibrary uses
+    //                                              everywhere and we read in
+    //                                              none of them)
+    //   jvmTarget = JvmTarget.JVM_21
+    //   jvmTarget.set(JvmTarget.fromTarget("17"))
+    const jvmTargetFromTargetRe = /jvmTarget\s*(?:=|\.set\s*\(\s*)\s*JvmTarget\.fromTarget\s*\(\s*["']([^"']+)["']/g;
+    while ((m = jvmTargetFromTargetRe.exec(content)) !== null) {
+        const v = parseJavaVersion(m[1]);
+        if (v)
+            candidates.push(v);
+    }
+    const jvmTargetRe = /jvmTarget\s*(?:=|\.set\s*\(\s*)\s*(?:JvmTarget\.)?["']?([A-Za-z0-9._]+)["']?/g;
     while ((m = jvmTargetRe.exec(content)) !== null) {
         const v = parseJavaVersion(m[1]);
         if (v)
@@ -309,6 +339,92 @@ function detectJavaVersionInContent(content) {
     }
     return candidates.length > 0 ? Math.max(...candidates) : undefined;
 }
+/** The builds a settings file composes in, e.g. `includeBuild("build-logic")`. */
+export function parseIncludedBuilds(content) {
+    if (!content || typeof content !== "string")
+        return [];
+    const builds = [];
+    for (const m of content.matchAll(/includeBuild\s*\(?\s*["']([^"']+)["']/g)) {
+        if (!builds.includes(m[1]))
+            builds.push(m[1]);
+    }
+    return builds;
+}
+/**
+ * A Java version pinned outside Gradle, and the file that pins it.
+ *
+ * `mihonapp/mihon` declares no Java level in any Gradle file and pins 21 in
+ * `.github/.java-version`, which its own workflows consume through
+ * `setup-java`'s `java-version-file:`. The project says what it needs; it
+ * just does not say it in Gradle, and reading only Gradle files scanned it as
+ * "nothing declared" and ran it on the default. Across the thirty clones,
+ * three repositories pin with a version file and ten name a version in a
+ * workflow.
+ *
+ * A pin is a **floor**, folded in with `Math.max` like every other
+ * declaration — not an override.
+ */
+export function detectPinnedJavaVersion(root) {
+    const found = [];
+    const offer = (version, source) => {
+        if (version !== undefined && version > 0)
+            found.push({ version, source });
+    };
+    for (const name of [".java-version", ".github/.java-version"]) {
+        const content = safeRead(resolve(root, name));
+        if (content)
+            offer(parseJavaVersion(content.trim().split("\n")[0] ?? ""), name);
+    }
+    // asdf / mise: `java temurin-21.0.3+9` — the major version is what matters.
+    const toolVersions = safeRead(resolve(root, ".tool-versions"));
+    if (toolVersions) {
+        const m = /^\s*java\s+(\S+)/m.exec(toolVersions);
+        if (m)
+            offer(parseJavaVersion(m[1].replace(/^[A-Za-z-]+-/, "")), ".tool-versions");
+    }
+    // SDKMAN: `java=17.0.9-tem`
+    const sdkmanrc = safeRead(resolve(root, ".sdkmanrc"));
+    if (sdkmanrc) {
+        const m = /^\s*java\s*=\s*(\S+)/m.exec(sdkmanrc);
+        if (m)
+            offer(parseJavaVersion(m[1]), ".sdkmanrc");
+    }
+    for (const workflow of listWorkflowFiles(root)) {
+        const content = safeRead(workflow);
+        if (!content)
+            continue;
+        const name = relative(root, workflow);
+        // `java-version: 21`, `java-version: '21'`, and a matrix list — take the
+        // highest, because that is the one that has to work.
+        for (const m of content.matchAll(/java-version\s*:\s*(.+)/g)) {
+            for (const token of m[1].split(/[,[\]\s]+/)) {
+                const cleaned = token.replace(/["']/g, "").trim();
+                if (cleaned)
+                    offer(parseJavaVersion(cleaned), name);
+            }
+        }
+        // `java-version-file: .github/.java-version` — read what it points at.
+        for (const m of content.matchAll(/java-version-file\s*:\s*["']?([^"'\s]+)/g)) {
+            const pinned = safeRead(resolve(root, m[1]));
+            if (pinned)
+                offer(parseJavaVersion(pinned.trim().split("\n")[0] ?? ""), m[1]);
+        }
+    }
+    if (found.length === 0)
+        return undefined;
+    return found.reduce((a, b) => (b.version > a.version ? b : a));
+}
+function listWorkflowFiles(root) {
+    const dir = resolve(root, ".github", "workflows");
+    try {
+        return readdirSync(dir)
+            .filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"))
+            .map((f) => resolve(dir, f));
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Returns the highest Java version requirement found across all Gradle files,
  * or undefined if none is detected.
@@ -350,20 +466,32 @@ function detectGradleWrapperVersion(projectRoot) {
  * when the version string says nothing usable.
  */
 export function gradleJavaCeiling(gradleVersion) {
-    const major = Number(/^(\d+)\./.exec(gradleVersion ?? "")?.[1]);
+    const parsed = /^(\d+)(?:\.(\d+))?/.exec(gradleVersion ?? "");
+    const major = parsed ? Number(parsed[1]) : NaN;
     if (!Number.isInteger(major))
         return undefined;
-    if (major <= 4)
-        return 8;
-    if (major === 5)
-        return 11;
-    if (major === 6)
-        return 15;
-    if (major === 7)
-        return 17;
-    if (major === 8)
+    const minor = Number(parsed?.[2] ?? 0);
+    const atLeast = (m, n) => major > m || (major === m && minor >= n);
+    // Minor-aware, because the boundaries are minor releases. While 17 was the
+    // preferred JDK this was harmless — the ceiling only had to be right about
+    // whether 17 fitted. Preferring the newest makes it load-bearing: JDK 21
+    // arrived in Gradle 8.5, so 8.0 through 8.4 answering "21" would hand those
+    // projects a JDK their own wrapper refuses to start on.
+    // Gradle 9.1 added JDK 25; 9.0 tops out at 24. Without this the six corpus
+    // repositories declaring a level above 21 would still abstain, because a
+    // floor of 25 against a ceiling of 24 intersects with nothing — installing
+    // JDK 25 buys nothing if no ceiling ever reaches it.
+    if (atLeast(9, 1))
+        return 25;
+    if (major >= 9)
+        return 24;
+    if (atLeast(8, 5))
         return 21;
-    return 24;
+    if (atLeast(7, 3))
+        return 17;
+    if (atLeast(5, 0))
+        return 11;
+    return 8;
 }
 /** The oldest Java release a given Gradle version will start on. */
 export function gradleJavaFloor(gradleVersion) {
@@ -378,48 +506,48 @@ export function gradleJavaFloor(gradleVersion) {
  *
  * 11 joined the images on 2026-09-05, for Gradle 5.x and 6.x — which cannot
  * *start* on 17, whatever the sources declare. It is a fallback, never a
- * preference; see `PREFERRED_JAVA_VERSION`.
+ * preference: the selection takes the newest JDK that fits, so 11 is reached
+ * only when a wrapper's ceiling leaves nothing else.
+ *
+ * 8 and 25 joined on 2026-09-07, the companion half of the "newest the
+ * wrapper allows" decision — the images carry every JDK we find a project
+ * asking for, rather than a project bending to what they carry. 8 is 11's
+ * argument one line further back (Gradle 4.x tops out at Java 8); 25 covers
+ * the six repositories in the 150-repo corpus that declare a level above 21.
+ * Nothing reaches 8 unless a wrapper ceiling forces it.
  */
-export const AVAILABLE_JAVA_VERSIONS = [11, 17, 21];
+export const AVAILABLE_JAVA_VERSIONS = [8, 11, 17, 21, 25];
 /**
- * The JDK to write whenever nothing forces otherwise.
- *
- * This is what makes 11 safe to list. The selection below used to answer with
- * the *lowest* usable JDK, which was harmless while the lowest was 17. With 11
- * installed that rule would write `JAVA_VERSION: 11` for every project whose
- * `sourceCompatibility` is 11 — and AGP 8.x will not run on JDK 11, so
- * pipelines that build today would stop building.
+ * The newest JDK a build machine carries. Named because it is what a
+ * generated pipeline falls back to when no JDK can satisfy the constraints —
+ * a pipeline has to write something, and `javaVersionProblem` says what was
+ * given up.
  */
-export const PREFERRED_JAVA_VERSION = 17;
+export const NEWEST_AVAILABLE_JAVA_VERSION = Math.max(...AVAILABLE_JAVA_VERSIONS);
 /**
- * The Java version to write into a generated pipeline: `PREFERRED_JAVA_VERSION`
- * whenever it satisfies both what the sources declare and what the Gradle
- * wrapper can run on, and the nearest available JDK that does when it cannot.
+ * The Java version to write into a generated pipeline: the **newest**
+ * available JDK that satisfies both what the sources declare and what the
+ * Gradle wrapper can run on.
  *
- * Source compatibility is a floor, not an exact request — a project
- * declaring 11 compiles fine on 17 — but it is not the only constraint.
- * Gradle starts before it reads a single `sourceCompatibility`, so a wrapper
- * pinning an old Gradle caps the JDK no matter what the sources say, and a
- * declaration above every installed JDK cannot be honoured at all.
+ * DECIDED 2026-09-06 (Alex), reversing Invarn PRD decision #15 ("17 is the
+ * JDK whenever nothing forces otherwise"). The thirty-app study measured the
+ * cost of preferring 17 in one direction and none in the other: two rows
+ * failed because 17 was too *low* for a build plugin's own runtime
+ * requirement, and no row failed because 21 was too high. A project targeting
+ * 17 runs fine on 21; never the reverse.
  *
- * Falls back to the preferred JDK — not the lowest — when the constraints
- * cannot all be met, because a pipeline has to name something and the
- * unsatisfiable cases are overwhelmingly "declared something newer than we
- * have", where 17 is a far better guess than 11. `javaVersionProblem` says
- * what was given up so the caller can warn.
+ * Source compatibility is a floor, not an exact request. Gradle starts before
+ * it reads a single `sourceCompatibility`, so a wrapper pinning an old Gradle
+ * caps the JDK no matter what the sources say — which is why the ceiling
+ * above had to learn minor versions before this could ship.
  */
 export function runnableJavaVersion(detectedJavaVersion, gradleVersion) {
     const ceiling = gradleJavaCeiling(gradleVersion) ?? Infinity;
     const floor = Math.max(detectedJavaVersion ?? 0, gradleJavaFloor(gradleVersion) ?? 0);
     const usable = AVAILABLE_JAVA_VERSIONS.filter((v) => v >= floor && v <= ceiling).sort((a, b) => a - b);
     if (usable.length === 0)
-        return PREFERRED_JAVA_VERSION;
-    if (usable.includes(PREFERRED_JAVA_VERSION))
-        return PREFERRED_JAVA_VERSION;
-    // Forced off the default: below it take the newest that fits under the
-    // ceiling, above it the oldest that clears the floor.
-    const below = usable.filter((v) => v < PREFERRED_JAVA_VERSION);
-    return below.length > 0 ? below[below.length - 1] : usable[0];
+        return NEWEST_AVAILABLE_JAVA_VERSION;
+    return usable[usable.length - 1];
 }
 /**
  * What `runnableJavaVersion` could not honour, as a sentence, or undefined
@@ -581,7 +709,14 @@ export async function scanAndroidProject(projectRoot) {
     // 2. Detect required Java version and build variants
     // ------------------------------------------------------------------
     const gradleFiles = findGradleFiles(projectRoot);
-    const detectedJavaVersion = detectRequiredJavaVersion(gradleFiles);
+    const declaredJavaVersion = detectRequiredJavaVersion(gradleFiles);
+    // A version file or a workflow pin is a floor like any declaration, and for
+    // a project that declares nothing in Gradle it is the only thing that says
+    // which JDK the build needs.
+    const pinnedJava = detectPinnedJavaVersion(projectRoot);
+    const detectedJavaVersion = declaredJavaVersion === undefined && pinnedJava === undefined
+        ? undefined
+        : Math.max(declaredJavaVersion ?? 0, pinnedJava?.version ?? 0);
     const detectedGradleVersion = detectGradleWrapperVersion(projectRoot);
     const buildVariants = detectBuildVariants(gradleFiles);
     // ------------------------------------------------------------------

package/dist/src/commands/ios-scanner.d.ts

@@ -9,8 +9,13 @@ export interface IosWarning {
 }
 export interface IosScanResult {
     warnings: IosWarning[];
-    /** Schemes detected from .xcscheme files inside .xcodeproj. Falls back to project name. */
+    /**
+     * Schemes detected from .xcscheme files inside .xcodeproj, **best first**.
+     * Falls back to the project name. Callers write `[0]` into IOS_SCHEME.
+     */
     detectedSchemes: string[];
+    /** Why `detectedSchemes[0]` is first, when more than one was found. */
+    schemeChoiceReason?: string;
     /** True if a Podfile exists in the project root. */
     hasCocoaPods: boolean;
     /** True if a Package.swift exists in the project root. */
@@ -22,6 +27,42 @@ export interface IosScanResult {
     /** DEVELOPMENT_TEAM value from project.pbxproj, or empty string if not found. */
     developmentTeam: string;
 }
+/**
+ * The detected schemes, best first.
+ *
+ * `detectedSchemes[0]` is what every caller writes into `IOS_SCHEME`, and it
+ * used to be whatever `readdirSync` returned first. A space (0x20) sorts
+ * before a period (0x2E), so `"<App> <Suffix>.xcscheme"` **always** lists
+ * before `"<App>.xcscheme"`: an app named after its own project loses to its
+ * extension or its tvOS companion every time. Four of the eight iOS rows that
+ * built in the thirty-app study were given a non-app scheme that way — Stay
+ * built its extension and reported "no test bundles available to test";
+ * Swiftfin built its tvOS scheme and could not find an iOS Simulator
+ * destination.
+ *
+ * The order, in the terms the scheme XML actually states:
+ *
+ *  1. named after the project or workspace — the commonest case, and
+ *     unambiguous;
+ *  2. launches the product named after the project, and is not named like a
+ *     companion. `thebaselab/codeapp` is why this outranks the next one: its
+ *     `Code App` scheme launches `Code.app` and declares no tests at all,
+ *     while `Code UI` has two test bundles and launches `CodeUI.app`;
+ *  3. launches an `.app`, declares tests (the template runs them), and is not
+ *     named like a companion; among several, the iOS or Debug one, then the
+ *     shortest;
+ *  4. launches an `.app` and is not named like a companion;
+ *  5. whatever order it came in.
+ *
+ * Every scheme stays in the list — this reorders, it does not filter, so a
+ * caller wanting the extension can still find it.
+ */
+export declare function rankSchemes(root: string, projectPath: string, schemes: string[]): string[];
+/** The ranking, plus the sentence explaining its first entry. */
+export declare function rankSchemesWithReason(root: string, projectPath: string, schemes: string[]): {
+    schemes: string[];
+    reason?: string;
+};
 export declare function scanIosProject(projectRoot: string): Promise<IosScanResult>;
 export declare function formatIosScanResult(result: IosScanResult): string;
 //# sourceMappingURL=ios-scanner.d.ts.map

package/dist/src/commands/ios-scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ios-scanner.d.ts","sourceRoot":"","sources":["../../../src/commands/ios-scanner.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG,SAAS,GAAG,gBAAgB,GAAG,WAAW,CAAC;AAE7F,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,2FAA2F;IAC3F,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,oDAAoD;IACpD,YAAY,EAAE,OAAO,CAAC;IACtB,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iFAAiF;IACjF,eAAe,EAAE,MAAM,CAAC;CACzB;AAyND,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAqFhF;AAaD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAkDjE"}
+{"version":3,"file":"ios-scanner.d.ts","sourceRoot":"","sources":["../../../src/commands/ios-scanner.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG,SAAS,GAAG,gBAAgB,GAAG,WAAW,CAAC;AAE7F,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB;;;OAGG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,YAAY,EAAE,OAAO,CAAC;IACtB,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iFAAiF;IACjF,eAAe,EAAE,MAAM,CAAC;CACzB;AA8ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,GAChB,MAAM,EAAE,CAEV;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,GAChB;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CA4CxC;AAmLD,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAgGhF;AAaD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAkDjE"}

package/dist/src/commands/ios-scanner.js

@@ -36,6 +36,115 @@ function findXcodeProjectPath(root) {
         return projects[0];
     return "";
 }
+/**
+ * Names a scheme carries when it builds something beside the app rather than
+ * the app: an extension, a widget, a watch or TV companion, a test or
+ * screenshot harness. Matched case-insensitively on the whole name.
+ */
+const COMPANION_SCHEME = /(extension|widget|clip|intents?|notification|tvos|macos|watchos|visionos|tests?|screenshots?|staging|prototype|codegen)/i;
+function readSchemeFacts(root, name) {
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".xcodeproj"))
+            continue;
+        const path = resolve(root, entry, "xcshareddata", "xcschemes", `${name}.xcscheme`);
+        if (!existsSync(path))
+            continue;
+        const xml = safeRead(path);
+        if (!xml)
+            continue;
+        const launch = /<LaunchAction[\s\S]*?<\/LaunchAction>/.exec(xml)?.[0] ?? "";
+        return {
+            runnable: /BuildableName\s*=\s*"([^"]+)"/.exec(launch)?.[1],
+            testable: /<TestableReference/.test(xml),
+        };
+    }
+    return undefined;
+}
+/**
+ * The detected schemes, best first.
+ *
+ * `detectedSchemes[0]` is what every caller writes into `IOS_SCHEME`, and it
+ * used to be whatever `readdirSync` returned first. A space (0x20) sorts
+ * before a period (0x2E), so `"<App> <Suffix>.xcscheme"` **always** lists
+ * before `"<App>.xcscheme"`: an app named after its own project loses to its
+ * extension or its tvOS companion every time. Four of the eight iOS rows that
+ * built in the thirty-app study were given a non-app scheme that way — Stay
+ * built its extension and reported "no test bundles available to test";
+ * Swiftfin built its tvOS scheme and could not find an iOS Simulator
+ * destination.
+ *
+ * The order, in the terms the scheme XML actually states:
+ *
+ *  1. named after the project or workspace — the commonest case, and
+ *     unambiguous;
+ *  2. launches the product named after the project, and is not named like a
+ *     companion. `thebaselab/codeapp` is why this outranks the next one: its
+ *     `Code App` scheme launches `Code.app` and declares no tests at all,
+ *     while `Code UI` has two test bundles and launches `CodeUI.app`;
+ *  3. launches an `.app`, declares tests (the template runs them), and is not
+ *     named like a companion; among several, the iOS or Debug one, then the
+ *     shortest;
+ *  4. launches an `.app` and is not named like a companion;
+ *  5. whatever order it came in.
+ *
+ * Every scheme stays in the list — this reorders, it does not filter, so a
+ * caller wanting the extension can still find it.
+ */
+export function rankSchemes(root, projectPath, schemes) {
+    return rankSchemesWithReason(root, projectPath, schemes).schemes;
+}
+/** The ranking, plus the sentence explaining its first entry. */
+export function rankSchemesWithReason(root, projectPath, schemes) {
+    if (schemes.length < 2)
+        return { schemes };
+    const projectName = projectPath.replace(/\.(xcodeproj|xcworkspace)$/, "").split("/").pop();
+    const scored = schemes.map((name, index) => {
+        const facts = readSchemeFacts(root, name);
+        const companion = COMPANION_SCHEME.test(name);
+        const app = facts?.runnable?.endsWith(".app") ?? false;
+        let tier = 4;
+        if (name === projectName)
+            tier = 0;
+        else if (facts?.runnable === `${projectName}.app` && !companion)
+            tier = 1;
+        else if (app && facts?.testable && !companion)
+            tier = 2;
+        else if (app && !companion)
+            tier = 3;
+        return {
+            name,
+            index,
+            tier,
+            // Within a tier: an iOS or Debug variant first, then the shorter name.
+            preferred: /(^|[^A-Za-z])(iOS|Debug)([^A-Za-z]|$)/i.test(name) ? 0 : 1,
+            length: name.length,
+        };
+    });
+    scored.sort((a, b) => a.tier - b.tier ||
+        a.preferred - b.preferred ||
+        a.length - b.length ||
+        a.index - b.index);
+    const best = scored[0];
+    const others = scored.length - 1;
+    const why = [
+        "named after the project",
+        `launches ${projectName}.app`,
+        "the app scheme that runs the tests",
+        "the only app scheme that is not a companion",
+        "first in the list, and nothing here separates them",
+    ][best.tier];
+    return {
+        schemes: scored.map((s) => s.name),
+        reason: `${best.name} — ${why}; ${others} other scheme${others === 1 ? "" : "s"} here`,
+    };
+}
 /**
  * Detects Xcode schemes by reading *.xcscheme files from the
  * xcshareddata/xcschemes/ directory inside a .xcodeproj bundle.
@@ -209,8 +318,10 @@ export async function scanIosProject(projectRoot) {
     const warnings = [];
     // 1. Find project path
     const projectPath = findXcodeProjectPath(projectRoot);
-    // 2. Detect schemes
-    const detectedSchemes = detectSchemes(projectRoot);
+    // 2. Detect schemes, best first — `detectedSchemes[0]` is what becomes
+    //    IOS_SCHEME, and the filesystem's order is not a ranking.
+    const ranked = rankSchemesWithReason(projectRoot, projectPath, detectSchemes(projectRoot));
+    const detectedSchemes = ranked.schemes;
     // 3. CocoaPods
     const hasCocoaPods = existsSync(resolve(projectRoot, "Podfile"));
     // 4. SPM
@@ -278,7 +389,16 @@ export async function scanIosProject(projectRoot) {
             });
         }
     }
-    return { warnings, detectedSchemes, hasCocoaPods, hasSPM, projectPath, hasSigningConfig, developmentTeam };
+    return {
+        warnings,
+        detectedSchemes,
+        ...(ranked.reason ? { schemeChoiceReason: ranked.reason } : {}),
+        hasCocoaPods,
+        hasSPM,
+        projectPath,
+        hasSigningConfig,
+        developmentTeam,
+    };
 }
 // ---------------------------------------------------------------------------
 // Formatter

package/dist/src/commands/ios-scheme-ranking.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ios-scheme-ranking.test.d.ts.map

package/dist/src/commands/ios-scheme-ranking.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ios-scheme-ranking.test.d.ts","sourceRoot":"","sources":["../../../src/commands/ios-scheme-ranking.test.ts"],"names":[],"mappings":""}