@invarn/cibuild 2.7.9 → 2.8.1

package/dist/src/commands/a-properties-stand-in-declares-the-keys-the-build-reads.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=a-properties-stand-in-declares-the-keys-the-build-reads.test.d.ts.map

package/dist/src/commands/a-properties-stand-in-declares-the-keys-the-build-reads.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a-properties-stand-in-declares-the-keys-the-build-reads.test.d.ts","sourceRoot":"","sources":["../../../src/commands/a-properties-stand-in-declares-the-keys-the-build-reads.test.ts"],"names":[],"mappings":""}

package/dist/src/commands/a-properties-stand-in-declares-the-keys-the-build-reads.test.js

@@ -0,0 +1,218 @@
+/**
+ * An empty properties file fixes "file missing", not "field missing".
+ *
+ * The Secrets Gradle plugin turns each key of the properties file it loads
+ * into a `BuildConfig` constant and a manifest placeholder. A checkout without
+ * that file gets neither, so handing the build an empty stand-in clears the
+ * plugin's own throw and then fails one step later, inside Gradle, at the first
+ * reference to a constant that was never generated.
+ *
+ * `missingPropertyKeys` is the list a stand-in has to declare for that
+ * reference to resolve: what the build reads, read off the build files and the
+ * source under the modules that apply the plugin.
+ */
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { scanAndroidProject } from "./android-scanner.js";
+let root;
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "cibuild-props-"));
+});
+afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+function write(relative, content) {
+    const path = join(root, relative);
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, content);
+}
+async function keys() {
+    return (await scanAndroidProject(root)).missingPropertyKeys;
+}
+/**
+ * The shape the whole thing is for: one module applying the plugin, no
+ * properties file anywhere, and the root declaring the plugin without
+ * applying it — which is where a version catalog alias is nearly always named.
+ */
+function projectApplyingTheSecretsPlugin(appBuildFileExtra = "") {
+    write("settings.gradle.kts", 'include(":app")\n');
+    write("build.gradle.kts", "plugins {\n  alias(libs.plugins.secrets) apply false\n}\n");
+    write("app/build.gradle.kts", `plugins {\n  id("com.android.application")\n  alias(libs.plugins.secrets)\n}\n\nandroid {\n  namespace = "com.example.app"\n${appBuildFileExtra}}\n`);
+    write(".gitignore", "local.properties\n");
+}
+describe("the keys a generated properties file has to declare", () => {
+    test("names a BuildConfig field referenced from Kotlin source", async () => {
+        projectApplyingTheSecretsPlugin();
+        write("app/src/main/java/com/example/app/Maps.kt", "package com.example.app\n\nval key: String = BuildConfig.MAPS_API_KEY\n");
+        expect(await keys()).toEqual(["MAPS_API_KEY"]);
+    });
+    test("names one referenced from Java source", async () => {
+        projectApplyingTheSecretsPlugin();
+        write("app/src/main/java/com/example/app/Maps.java", "package com.example.app;\n\nclass Maps { String k = BuildConfig.MAPS_API_KEY; }\n");
+        expect(await keys()).toEqual(["MAPS_API_KEY"]);
+    });
+    test("names a manifestPlaceholders key — Kotlin DSL, indexed", async () => {
+        projectApplyingTheSecretsPlugin('  defaultConfig {\n    manifestPlaceholders["mapsApiKey"] = "unused"\n  }\n');
+        expect(await keys()).toEqual(["mapsApiKey"]);
+    });
+    test("names a manifestPlaceholders key — Kotlin DSL, whole map", async () => {
+        projectApplyingTheSecretsPlugin('  defaultConfig {\n    manifestPlaceholders += mapOf("mapsApiKey" to "u", "adsAppId" to "u")\n  }\n');
+        expect(await keys()).toEqual(["adsAppId", "mapsApiKey"]);
+    });
+    test("names a manifestPlaceholders key — Groovy map literal", async () => {
+        write("settings.gradle", "include ':app'\n");
+        write("build.gradle", "// root\n");
+        write("app/build.gradle", "plugins {\n  id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'\n}\n" +
+            "android {\n  defaultConfig {\n" +
+            "    manifestPlaceholders = [mapsApiKey: \"unused\", 'adsAppId': \"unused\"]\n" +
+            "  }\n}\n");
+        expect(await keys()).toEqual(["adsAppId", "mapsApiKey"]);
+    });
+    test("names a manifestPlaceholders key — Groovy put", async () => {
+        write("settings.gradle", "include ':app'\n");
+        write("build.gradle", "// root\n");
+        write("app/build.gradle", "plugins {\n  id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'\n}\n" +
+            "android {\n  defaultConfig {\n" +
+            "    manifestPlaceholders.put('mapsApiKey', 'unused')\n" +
+            "  }\n}\n");
+        expect(await keys()).toEqual(["mapsApiKey"]);
+    });
+    test("merges both sources, sorted and deduplicated", async () => {
+        projectApplyingTheSecretsPlugin('  defaultConfig {\n    manifestPlaceholders["MAPS_API_KEY"] = "u"\n  }\n');
+        write("app/src/main/java/com/example/app/Keys.kt", "val a = BuildConfig.MAPS_API_KEY\nval b = BuildConfig.ADS_APP_ID\nval c = BuildConfig.MAPS_API_KEY\n");
+        expect(await keys()).toEqual(["ADS_APP_ID", "MAPS_API_KEY"]);
+    });
+});
+describe("what it deliberately leaves out", () => {
+    /**
+     * `BuildConfig.DEBUG` is the most-referenced constant in Android source, and
+     * AGP generates it whether or not a properties file exists. Declaring it
+     * would make the Secrets plugin generate a `String DEBUG` beside AGP's
+     * `boolean DEBUG` — the file meant to rescue the build breaking it instead.
+     */
+    test("the fields AGP generates by itself", async () => {
+        projectApplyingTheSecretsPlugin();
+        write("app/src/main/java/com/example/app/Env.kt", [
+            "val d = BuildConfig.DEBUG",
+            "val a = BuildConfig.APPLICATION_ID",
+            "val t = BuildConfig.BUILD_TYPE",
+            "val f = BuildConfig.FLAVOR",
+            "val fd = BuildConfig.FLAVOR_environment",
+            "val vc = BuildConfig.VERSION_CODE",
+            "val vn = BuildConfig.VERSION_NAME",
+            "val lp = BuildConfig.LIBRARY_PACKAGE_NAME",
+            "val mine = BuildConfig.MAPS_API_KEY",
+        ].join("\n"));
+        expect(await keys()).toEqual(["MAPS_API_KEY"]);
+    });
+    test("a project that applies no Secrets plugin", async () => {
+        write("settings.gradle.kts", 'include(":app")\n');
+        write("build.gradle.kts", "// root\n");
+        write("app/build.gradle.kts", 'plugins {\n  id("com.android.application")\n}\n');
+        write("app/src/main/java/com/example/app/Maps.kt", "val k = BuildConfig.MAPS_API_KEY\n");
+        expect(await keys()).toEqual([]);
+    });
+    /**
+     * `apply false` names the plugin's version for the modules that will apply
+     * it; the root project loads no properties file of its own. Reading it as an
+     * application would aim the source walk at the whole repository — every
+     * module's source, on the strength of a line that applies nothing.
+     */
+    test("a root that declares the plugin with apply false", async () => {
+        write("settings.gradle.kts", 'include(":app", ":other")\n');
+        write("build.gradle.kts", "plugins {\n  alias(libs.plugins.secrets) apply false\n}\n");
+        write("app/build.gradle.kts", 'plugins {\n  id("com.android.application")\n}\n');
+        write("other/build.gradle.kts", "// nothing\n");
+        write("other/src/main/java/Other.kt", "val k = BuildConfig.ELSEWHERE\n");
+        expect(await keys()).toEqual([]);
+    });
+    test("generated sources under build/", async () => {
+        projectApplyingTheSecretsPlugin();
+        write("app/build/generated/source/buildConfig/debug/com/example/app/BuildConfig.java", "public final class BuildConfig { public static final String STALE = BuildConfig.STALE; }\n");
+        write("app/src/main/java/com/example/app/Maps.kt", "val k = BuildConfig.MAPS_API_KEY\n");
+        expect(await keys()).toEqual(["MAPS_API_KEY"]);
+    });
+});
+describe("the module boundary", () => {
+    test("reads source of the module that applies the plugin, not its siblings", async () => {
+        write("settings.gradle.kts", 'include(":app", ":other")\n');
+        write("build.gradle.kts", "// root\n");
+        write("app/build.gradle.kts", 'plugins {\n  alias(libs.plugins.secrets)\n}\n');
+        write("app/src/main/java/App.kt", "val k = BuildConfig.MAPS_API_KEY\n");
+        write("other/build.gradle.kts", "// nothing\n");
+        write("other/src/main/java/Other.kt", "val k = BuildConfig.ELSEWHERE\n");
+        expect(await keys()).toEqual(["MAPS_API_KEY"]);
+    });
+    test("a root module that really applies the plugin covers the whole tree", async () => {
+        write("settings.gradle.kts", 'include(":app")\n');
+        write("build.gradle.kts", 'plugins {\n  id("com.android.application")\n  alias(libs.plugins.secrets)\n}\n');
+        write("app/build.gradle.kts", "// nothing\n");
+        write("app/src/main/java/App.kt", "val k = BuildConfig.MAPS_API_KEY\n");
+        expect(await keys()).toEqual(["MAPS_API_KEY"]);
+    });
+});
+/**
+ * The warnings a customer already sees. This scan adds a field and reads more
+ * files; it must not add, drop or reword a single warning, so the two paths
+ * that emit a `secrets-plugin` warning are asserted whole.
+ */
+describe("the Secrets-plugin warning path is unchanged", () => {
+    test("with no companion defaults file, the one file-absent warning", async () => {
+        projectApplyingTheSecretsPlugin();
+        write("app/src/main/java/com/example/app/Maps.kt", "val k = BuildConfig.MAPS_API_KEY\n");
+        const result = await scanAndroidProject(root);
+        expect(result.warnings.filter((w) => w.category === "secrets-plugin")).toEqual([
+            {
+                category: "secrets-plugin",
+                severity: "warning",
+                message: "Google Secrets Gradle Plugin reads 'local.properties' which is absent in CI",
+                hint: "Inject 'local.properties' as a file step using a secret variable",
+                // The root build file, which is where the version-catalog alias is
+                // named with `apply false`. The warning path counts that as an
+                // application and always has; `missingPropertyKeys` does not, which is
+                // why the two ask the question through different functions.
+                location: "build.gradle.kts",
+            },
+        ]);
+        // And the new field is populated in the same scan, from the same files.
+        expect(result.missingPropertyKeys).toEqual(["MAPS_API_KEY"]);
+    });
+    test("with a companion defaults file, one warning per expected key", async () => {
+        projectApplyingTheSecretsPlugin();
+        write("secrets.defaults.properties", "MAPS_API_KEY=\nADS_APP_ID=\n");
+        write("app/src/main/java/com/example/app/Maps.kt", "val k = BuildConfig.MAPS_API_KEY\n");
+        const result = await scanAndroidProject(root);
+        expect(result.warnings.filter((w) => w.category === "secrets-plugin")).toEqual([
+            {
+                category: "secrets-plugin",
+                severity: "warning",
+                message: "Secrets plugin key: MAPS_API_KEY",
+                hint: "Add via: ci secrets add MAPS_API_KEY",
+                location: "local.properties",
+            },
+            {
+                category: "secrets-plugin",
+                severity: "warning",
+                message: "Secrets plugin key: ADS_APP_ID",
+                hint: "Add via: ci secrets add ADS_APP_ID",
+                location: "local.properties",
+            },
+        ]);
+    });
+    test("a properties file that is present but not gitignored warns about neither", async () => {
+        write("settings.gradle.kts", 'include(":app")\n');
+        write("build.gradle.kts", "// root\n");
+        write("app/build.gradle.kts", "plugins {\n  alias(libs.plugins.secrets)\n}\n");
+        write("local.properties", "sdk.dir=/opt/android\n");
+        write("app/src/main/java/App.kt", "val k = BuildConfig.MAPS_API_KEY\n");
+        const result = await scanAndroidProject(root);
+        expect(result.warnings.filter((w) => w.category === "secrets-plugin")).toEqual([]);
+        // The keys are still reported. `invarn`-style callers run this scan on a
+        // developer's own checkout, where the file is nearly always present and
+        // holds nothing but `sdk.dir` — gating the keys on its absence would
+        // return nothing in exactly the case they are needed for.
+        expect(result.missingPropertyKeys).toEqual(["MAPS_API_KEY"]);
+    });
+});
+//# sourceMappingURL=a-properties-stand-in-declares-the-keys-the-build-reads.test.js.map

package/dist/src/commands/android-java-version.test.js

@@ -63,8 +63,14 @@ describe('runnableJavaVersion', () => {
         expect(runnableJavaVersion(17)).toBe(25);
         expect(runnableJavaVersion(25)).toBe(25);
     });
-    test('takes the newest available JDK when nothing is declared', () => {
-        expect(runnableJavaVersion(undefined)).toBe(25);
+    // Nothing declared and no wrapper to read is nothing to go on. It used to
+    // answer 25 anyway, which is a guess wearing a number; the generator's own
+    // default stands instead, and that is not news worth a warning.
+    test('abstains when there is nothing to go on', () => {
+        expect(runnableJavaVersion(undefined)).toBeUndefined();
+    });
+    test('still answers from the wrapper alone, with nothing declared', () => {
+        expect(runnableJavaVersion(undefined, '8.9')).toBe(21);
     });
     // 8 joined the images on 2026-09-07 and must stay unreachable except where
     // a wrapper ceiling forces it: a project declaring `sourceCompatibility 1.8`
@@ -84,17 +90,58 @@ describe('runnableJavaVersion', () => {
         expect(runnableJavaVersion(11, '5.2.1')).toBe(11);
         expect(runnableJavaVersion(undefined, '6.9')).toBe(11);
     });
+    // No answer is ever a JDK the build machines lack.
     test('never names a JDK no build machine has', () => {
-        expect(AVAILABLE_JAVA_VERSIONS).toContain(runnableJavaVersion(23));
-        expect(AVAILABLE_JAVA_VERSIONS).toContain(runnableJavaVersion(25, '8.9'));
-    });
-    test('lets an old wrapper cap a newer declaration', () => {
-        // Gradle 7.x tops out at 17 even though newer JDKs are installed. There
-        // is no usable JDK at all, so the pipeline names the newest and the
-        // caller warns — `javaVersionProblem` is what says so.
-        expect(runnableJavaVersion(21, '7.6.1')).toBe(25);
+        for (const answer of [runnableJavaVersion(23), runnableJavaVersion(25, '8.9')]) {
+            if (answer !== undefined)
+                expect(AVAILABLE_JAVA_VERSIONS).toContain(answer);
+        }
+    });
+    /**
+     * And no answer is ever above the wrapper's own ceiling.
+     *
+     * This is the defect. Nothing satisfied both the declaration and the
+     * ceiling, so the chooser fell back to the newest installed JDK — which is
+     * *above* the ceiling by construction, because the ceiling is why nothing
+     * fitted. The build then died selecting the JDK, exactly as a too-new JDK
+     * always does, and `javaVersionProblem` had no branch for the shape so
+     * nothing anywhere said a choice had been made.
+     *
+     * The ceiling is hard: Gradle starts before it reads a single
+     * `sourceCompatibility`. The declaration is a floor. So where they conflict
+     * the ceiling wins, and the caller says so.
+     */
+    test('never answers above the wrapper ceiling', () => {
+        // Gradle 7.x tops out at 17. Declaring 21 cannot raise that.
+        expect(runnableJavaVersion(21, '7.6.1')).toBe(17);
         expect(runnableJavaVersion(17, '7.6.1')).toBe(17);
     });
+    // Gradle 6.5 runs on Java 11 at most, and a workflow pins java-version 12.
+    // The old chooser answered 25 and said nothing.
+    test('caps a modern declaration under an old wrapper', () => {
+        expect(runnableJavaVersion(12, '6.5')).toBe(11);
+    });
+    // Every shape the corpus has, held to both properties at once: the answer
+    // is installed, and it is not above the ceiling.
+    test.each([
+        [8, '4.10.2'],
+        [11, '5.2.1'],
+        [12, '6.5'],
+        [17, '7.6.1'],
+        [21, '7.6.1'],
+        [8, '9.0'],
+        [30, '8.9'],
+        [25, '9.1'],
+        [undefined, '6.9'],
+    ])('declared %s on Gradle %s answers within both bounds', (declared, gradle) => {
+        const answer = runnableJavaVersion(declared, gradle);
+        if (answer === undefined)
+            return; // abstention is always allowed
+        expect(AVAILABLE_JAVA_VERSIONS).toContain(answer);
+        const ceiling = gradleJavaCeiling(gradle);
+        if (ceiling !== undefined)
+            expect(answer).toBeLessThanOrEqual(ceiling);
+    });
     test('honours the Gradle 9 floor of 17', () => {
         // The floor rules 11 out; the newest above it is what gets written.
         expect(runnableJavaVersion(8, '9.0')).toBe(21);
@@ -122,5 +169,41 @@ describe('javaVersionProblem', () => {
         // Nor is 4.10.2, since the images carry 8.
         expect(javaVersionProblem(undefined, '4.10.2')).toBeUndefined();
     });
+    /**
+     * The shape that used to fall through every branch, and the reason this
+     * function is resolved from the same place as the answer.
+     *
+     * A wrapper on Gradle 6.5 under a workflow pinning java-version 12: the
+     * ceiling is not below every installed JDK and the declaration is not above
+     * every installed JDK, so neither old branch fired. The chooser answered 25
+     * — above the ceiling — and nothing said the project had asked for something
+     * else and been overruled.
+     */
+    test('speaks when an old wrapper overrules a newer declaration', () => {
+        const problem = javaVersionProblem(12, '6.5');
+        expect(problem).toContain('Java 12');
+        expect(problem).toContain('Gradle 6.5');
+        expect(problem).toContain('Java 11 at most');
+        expect(problem).toContain('Building on 11');
+    });
+    // An answer that is not what was asked for always speaks, whichever
+    // constraint did the overruling.
+    test.each([
+        [12, '6.5'],
+        [21, '7.6.1'],
+        [30, '8.9'],
+    ])('declared %s on Gradle %s never passes silently', (declared, gradle) => {
+        expect(javaVersionProblem(declared, gradle)).toBeDefined();
+    });
+    // Naming a version with no provenance sends a reader through every Gradle
+    // file looking for a number that is in none of them. The scan knows which
+    // file asked, so the sentence can say.
+    test('names the file that asked, when it is known', () => {
+        const problem = javaVersionProblem(12, '6.5', '.github/workflows/Build.yml');
+        expect(problem).toContain('Java 12 (.github/workflows/Build.yml)');
+    });
+    test('reads correctly without a source', () => {
+        expect(javaVersionProblem(12, '6.5')).not.toContain('(');
+    });
 });
 //# sourceMappingURL=android-java-version.test.js.map

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

@@ -11,10 +11,42 @@ export interface ScanResult {
     warnings: BuildWarning[];
     /** Highest Java version requirement detected in Gradle files (e.g. 17, 21). */
     detectedJavaVersion?: number;
+    /**
+     * The file that asked for it, when the level came from outside Gradle —
+     * `.github/workflows/Build.yml`, `.java-version`, `.tool-versions`.
+     *
+     * The scan computed this and dropped it, so a warning could name a version
+     * with no provenance and send a reader looking through every Gradle file for
+     * a number that is not in any of them. Undefined when the level came from a
+     * Gradle file, or when a Gradle file asked for at least as much.
+     */
+    detectedJavaVersionSource?: string;
     /** Gradle version the wrapper pins, e.g. "8.9". Undefined when there is no wrapper. */
     detectedGradleVersion?: string;
     /** Build types, product flavors, and all variant combinations detected in Gradle files. */
     buildVariants: BuildVariants;
+    /**
+     * The property names the build reads out of the properties file the Secrets
+     * Gradle plugin loads — sorted, deduplicated, empty when no module applies
+     * the plugin.
+     *
+     * **An empty properties file fixes "file missing", not "field missing".**
+     * The plugin turns each key of that file into a `BuildConfig` constant and a
+     * manifest placeholder, so a checkout without the file compiles neither.
+     * Supplying an empty stand-in gets the build past the plugin's own throw and
+     * then fails one step later, inside Gradle, at the first reference to a field
+     * that was never generated. These are those names: what a stand-in has to
+     * declare for the reference to resolve.
+     *
+     * Data, not prose — deliberately not more `warnings`. A warning is a sentence
+     * for a human to read; this is a list for a generator to consume, and sharing
+     * one channel between them means the generator has to parse English.
+     *
+     * Coarse on purpose. A name here that some other plugin turns out to
+     * generate costs one unused line in a properties file; a name missing from
+     * here costs the build.
+     */
+    missingPropertyKeys: string[];
 }
 export interface BuildVariants {
     /** Build types found, e.g. ["debug", "release", "staging"]. Always includes debug + release. */
@@ -102,12 +134,71 @@ export declare function gradleJavaFloor(gradleVersion: string | undefined): numb
  */
 export declare const AVAILABLE_JAVA_VERSIONS: number[];
 /**
- * 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.
+ * The newest JDK a build machine carries.
+ *
+ * It is no longer what the chooser falls back to. It used to be: with no JDK
+ * satisfying both the sources and the wrapper, `runnableJavaVersion` returned
+ * this — which on a project pinning a modern Java level under an old Gradle
+ * wrapper is a JDK **above** that wrapper's ceiling, and the build dies at
+ * `:app:processDebugMainManifest` with "module java.base does not opens
+ * java.io to unnamed module". A number above the ceiling is not a fallback;
+ * it is the failure, chosen deliberately and reported as success.
  */
 export declare const NEWEST_AVAILABLE_JAVA_VERSION: number;
+/** Why the chooser answered as it did. See {@link chooseJavaVersion}. */
+export type JavaVersionKind = "unknown" | "satisfies" | "capped-by-wrapper" | "above-runners" | "wrapper-below-runners";
+/** The JDK choice and the reason for it, resolved together. */
+export interface JavaVersionChoice {
+    /** The JDK to write, or undefined where no answer exists. */
+    version: number | undefined;
+    kind: JavaVersionKind;
+    /** The highest level the project asked for, or 0 if it asked for none. */
+    declared: number;
+    /** The newest JDK the wrapper can start on, or undefined if unreadable. */
+    ceiling: number | undefined;
+    installed: number[];
+}
+/**
+ * The JDK to build on, with the reason attached — one place where the
+ * constraints are resolved, so the answer and the explanation cannot disagree.
+ *
+ * They used to. The chooser fell back to the newest installed JDK whenever
+ * nothing satisfied both constraints, and the sentence beside it had two
+ * branches — a ceiling below every installed JDK, and a declaration above
+ * every installed JDK — so the commonest shape of all fell through both and
+ * said nothing at all. A project pinning Java 12 against a Gradle wrapper that
+ * runs on 11 at most got Java 25 and silence.
+ *
+ * Three facts decide it:
+ *
+ *  - **What the build machine has.** Only `AVAILABLE_JAVA_VERSIONS` exist, so
+ *    a project declaring 30 cannot simply be given 30.
+ *  - **What Gradle can run on.** The wrapper sets a ceiling that source
+ *    compatibility cannot raise: Gradle starts before it reads a single
+ *    `sourceCompatibility`.
+ *  - **What the sources ask for.** A declaration is a floor, not an exact
+ *    request — a project declaring 11 compiles fine on 21.
+ *
+ * `kind` distinguishes the five outcomes:
+ *
+ *  - `unknown` — nothing declared and no readable wrapper. Nothing to go on
+ *    and nothing to say.
+ *  - `satisfies` — an installed JDK meets both the floor and the ceiling.
+ *  - `capped-by-wrapper` — nothing meets both, and the wrapper is why. The
+ *    ceiling is hard and the declaration is a preference, so the newest JDK
+ *    the wrapper *can* run is the answer, and the caller says so.
+ *  - `above-runners` — the declaration is above every installed JDK, and that
+ *    rather than the wrapper is what binds. **No answer**: asking for it would
+ *    fail when the JDK is selected, and quietly picking a lower one would be
+ *    the guess this exists to avoid.
+ *  - `wrapper-below-runners` — the ceiling is below every installed JDK. No
+ *    answer exists.
+ *
+ * `above-runners` is checked before `capped-by-wrapper` so a project declaring
+ * 99 against a modern wrapper is told about the machines rather than about its
+ * wrapper: both bind, and the one it can act on is the one worth naming.
+ */
+export declare function chooseJavaVersion(detectedJavaVersion: number | undefined, gradleVersion?: string): JavaVersionChoice;
 /**
  * The Java version to write into a generated pipeline: the **newest**
  * available JDK that satisfies both what the sources declare and what the
@@ -125,12 +216,22 @@ export declare const NEWEST_AVAILABLE_JAVA_VERSION: number;
  * 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 declare function runnableJavaVersion(detectedJavaVersion: number | undefined, gradleVersion?: string): number;
+export declare function runnableJavaVersion(detectedJavaVersion: number | undefined, gradleVersion?: string): number | undefined;
 /**
- * What `runnableJavaVersion` could not honour, as a sentence, or undefined
- * when it honoured everything.
+ * What the choice could not honour, as a sentence, or undefined when it
+ * honoured everything.
+ *
+ * Silence is the failure this exists to prevent: a pipeline that quietly
+ * overruled what a project asked for reads as the project's own problem, and
+ * the commonest shape of all — an old wrapper under a modern declaration — was
+ * the one that used to fall through every branch.
+ *
+ * `source` names the file that asked, when the caller knows it. The scan now
+ * returns it, so "asks for Java 12" can become "asks for Java 12
+ * (.github/workflows/Build.yml)" — a version with no provenance sends a reader
+ * looking through every Gradle file for a number that is not in any of them.
  */
-export declare function javaVersionProblem(detectedJavaVersion: number | undefined, gradleVersion?: string): string | undefined;
+export declare function javaVersionProblem(detectedJavaVersion: number | undefined, gradleVersion?: string, source?: string): string | undefined;
 /**
  * Detects build types and product flavors from Gradle files by static parsing,
  * falling back to the module's source sets for the flavors when no Gradle file

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

@@ -1 +1 @@
-{"version":3,"file":"android-scanner.d.ts","sourceRoot":"","sources":["../../../src/commands/android-scanner.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,MAAM,CAAC;AAEjD,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,SAAS,GACT,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,UAAU,GACV,gBAAgB,CAAC;AAErB,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,+EAA+E;IAC/E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uFAAuF;IACvF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,2FAA2F;IAC3F,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,gGAAgG;IAChG,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,wFAAwF;IACxF,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,uFAAuF;IACvF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAwKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAcnE;AAyKD,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAO7D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,GACX;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA8CjD;AA2BD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG7E;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAsBvF;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIrF;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uBAAuB,UAAsB,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,QAAuC,CAAC;AAElF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,mBAAmB,EAAE,MAAM,GAAG,SAAS,EACvC,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CAQR;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,mBAAmB,EAAE,MAAM,GAAG,SAAS,EACvC,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,GAAG,SAAS,CAkBpB;AAwLD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,aAAa,CAsCxE;AAMD,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAoQjF;AAgBD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAyD3D"}
+{"version":3,"file":"android-scanner.d.ts","sourceRoot":"","sources":["../../../src/commands/android-scanner.ts"],"names":[],"mappings":"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"}