laneyard 0.3.0 → 0.4.0

package/dist/src/heuristics/android-root.js

@@ -0,0 +1,49 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { parseAndroidSigning } from "./android-signing.js";
+/**
+ * Which build script speaks for the android side of a project — asked once, in
+ * one place.
+ *
+ * Two callers need the answer and they must never disagree. The checklist reads
+ * the script to decide whether a release build could go out signed with the
+ * debug key, and the runner writes the properties file that build asks for. If
+ * one of them stopped at `app/build.gradle` while the other read
+ * `android/app/build.gradle.kts`, the file would land where nothing reads it and
+ * the checklist would report green over an artifact signed by the debug key —
+ * the exact failure both of them exist to prevent. A shared list is what makes
+ * that disagreement impossible rather than unlikely.
+ *
+ * The order is a preference, not a ranking of correctness: `android/app` is
+ * where Flutter and React Native put theirs, and `app` is a repository that is
+ * an Android project outright. A repository with both is a monorepo whose
+ * fastlane directory should have pointed one level down, and the first match is
+ * the honest guess to make until it does.
+ */
+export const ANDROID_BUILD_SCRIPTS = [
+    "android/app/build.gradle.kts",
+    "android/app/build.gradle",
+    "app/build.gradle.kts",
+    "app/build.gradle",
+];
+/**
+ * Reads the first android build script under `root`, or null when there is none.
+ *
+ * `root` is the app root inside the clone, not the repository root: in a
+ * monorepo the app is one directory down and so are its platform folders.
+ *
+ * Never throws. An unreadable script is the same as an absent one to both
+ * callers — "could not tell" — and a checklist that raised here would turn a
+ * question it failed to answer into an error page.
+ */
+export async function findAndroidBuild(root) {
+    for (const candidate of ANDROID_BUILD_SCRIPTS) {
+        const scriptPath = join(root, candidate);
+        const text = await readFile(scriptPath, "utf8").catch(() => null);
+        if (text === null)
+            continue;
+        const moduleDir = dirname(scriptPath);
+        return { scriptPath, moduleDir, gradleRoot: dirname(moduleDir), facts: parseAndroidSigning(text) };
+    }
+    return null;
+}

package/dist/src/heuristics/android-signing.js

@@ -0,0 +1,98 @@
+/**
+ * Whether a release build is actually signed with the release key.
+ *
+ * The pattern this exists for is in the Flutter documentation, and therefore in
+ * thousands of projects:
+ *
+ *     signingConfig = if (keystorePropertiesFile.exists()) {
+ *         signingConfigs.getByName("release")
+ *     } else {
+ *         signingConfigs.getByName("debug")
+ *     }
+ *
+ * It is kind locally — `flutter run --release` works on a machine with no
+ * keystore — and it is a trap everywhere else. `key.properties` is gitignored
+ * by the same documentation, so it is by definition absent from a clone. The
+ * release build then *succeeds*, produces an `.aab` signed with the debug key,
+ * and the failure arrives minutes later from Google, saying nothing about
+ * signing.
+ *
+ * Silent, late, and misleading — which is exactly the shape of failure a
+ * checklist exists to move forward in time.
+ *
+ * Text, not a Gradle evaluation: running someone's build script to ask it a
+ * question is not something a checklist may do. So this errs towards saying
+ * nothing, and the check it feeds says "could not tell" rather than inventing a
+ * verdict from a file it half understood.
+ */
+export const NO_SIGNING_FACTS = {
+    releaseCanUseDebugKey: false,
+    conditionalOn: null,
+};
+/**
+ * `rootProject.file("key.properties")`, `file('signing.properties')` — the name,
+ * and whatever the call was made on.
+ *
+ * The receiver is optional and captured separately because it is the whole
+ * difference between two directories. It is matched as a dotted chain so that
+ * the match starts at the receiver rather than at `file(` in the middle of it:
+ * a pattern that ignored the receiver would read `keystoreDir.file(…)` as a bare
+ * call and confidently name the wrong place.
+ */
+const PROPERTIES_FILE = /(?:([A-Za-z_][\w.]*)\s*\.\s*)?\bfile\s*\(\s*["']([^"']+\.properties)["']\s*\)/;
+/**
+ * `project.file` is the bare call spelled out — Gradle defines one as the other
+ * — so both mean the module. Only `rootProject` climbs, and anything else is a
+ * receiver whose directory this has no way to know.
+ */
+function scopeOf(receiver) {
+    if (receiver === undefined || receiver === "project")
+        return "module";
+    if (receiver === "rootProject")
+        return "root";
+    return "unknown";
+}
+/**
+ * The `release { … }` block of `buildTypes`, as text.
+ *
+ * Braces are counted rather than matched with a regex, because the block nests
+ * and a lazy match would stop at the first `}` — which is usually inside it.
+ */
+function releaseBlock(source) {
+    const start = /buildTypes\s*\{/.exec(source);
+    if (!start)
+        return null;
+    const from = source.indexOf("release", start.index);
+    if (from === -1)
+        return null;
+    const open = source.indexOf("{", from);
+    if (open === -1)
+        return null;
+    let depth = 0;
+    for (let i = open; i < source.length; i += 1) {
+        if (source[i] === "{")
+            depth += 1;
+        else if (source[i] === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return source.slice(open, i + 1);
+        }
+    }
+    return null;
+}
+/** Reads an `android/app/build.gradle` or its Kotlin equivalent. Never throws. */
+export function parseAndroidSigning(source) {
+    const release = releaseBlock(source);
+    if (release === null)
+        return NO_SIGNING_FACTS;
+    // `signingConfigs.debug` and `signingConfigs.getByName("debug")` are the two
+    // spellings; both mean the release build may go out with the debug key.
+    const usesDebug = /signingConfigs\s*(?:\.getByName\s*\(\s*["']debug["']\s*\)|\.debug\b)/.test(release);
+    const conditional = PROPERTIES_FILE.exec(source);
+    return {
+        releaseCanUseDebugKey: usesDebug,
+        conditionalOn: usesDebug && conditional
+            ? { name: conditional[2], scope: scopeOf(conditional[1]) }
+            : null,
+    };
+}

package/dist/src/heuristics/appfile.js

@@ -0,0 +1,60 @@
+/**
+ * What fastlane's `Appfile` says about credentials.
+ *
+ * The Appfile is the other half of a fastlane setup, and the half Laneyard used
+ * to be blind to: a project whose Play Store service account has been configured
+ * for years — `json_key_file` on line two — was told it had no service account,
+ * because the only place the checklist looked was Laneyard's own vault. A
+ * warning that is false for a working project is worse than no warning: it is
+ * the one that teaches someone the screen is wrong and can be skipped.
+ *
+ * This is a reader, not an evaluator. The Appfile is Ruby and may compute its
+ * values — `json_key_file ENV["KEY"]` is legal and common — so anything that is
+ * not a plain string literal is reported as "set, but not to something readable
+ * from here" rather than guessed at. The checks turn that into `unknown`, which
+ * is the honest answer: the value exists, and whether it resolves to a file on
+ * this machine is not a question a text file can settle.
+ */
+const ABSENT = { kind: "absent" };
+export const NO_APPFILE = {
+    jsonKeyFile: ABSENT,
+    jsonKeyData: ABSENT,
+    appleId: ABSENT,
+};
+/**
+ * Strips comments, so `# json_key_file "old.json"` is not read as a setting.
+ *
+ * Naive about `#` inside a string, deliberately: the alternative is a Ruby
+ * lexer, and the cost of being wrong here is one line read as a comment — the
+ * check answers "not found" instead of "found", which is the direction this
+ * whole module errs in anyway.
+ */
+const withoutComments = (line) => line.replace(/#.*$/, "");
+/**
+ * `json_key_file "x"`, `json_key_file("x")`, `json_key_file 'x'` — and the
+ * `for_platform`/`for_lane` blocks they may sit inside, which change nothing
+ * about whether the key is set, only about when.
+ */
+function read(lines, key) {
+    const declaration = new RegExp(`^\\s*${key}\\s*(\\(|\\s)`);
+    const literal = new RegExp(`^\\s*${key}\\s*\\(?\\s*(["'])(.*?)\\1\\s*\\)?\\s*$`);
+    let found = ABSENT;
+    for (const line of lines) {
+        if (!declaration.test(line))
+            continue;
+        const match = literal.exec(line);
+        // A later assignment wins, the way it would when Ruby runs the file — and a
+        // literal that follows a computed one is still the value that lands.
+        found = match ? { kind: "literal", value: match[2] } : { kind: "computed" };
+    }
+    return found;
+}
+/** Reads an Appfile's text. Never throws: an unreadable Appfile is `NO_APPFILE`. */
+export function parseAppfile(content) {
+    const lines = content.split("\n").map(withoutComments);
+    return {
+        jsonKeyFile: read(lines, "json_key_file"),
+        jsonKeyData: read(lines, "json_key_data"),
+        appleId: read(lines, "apple_id"),
+    };
+}

package/dist/src/heuristics/blocking-actions.js

@@ -42,6 +42,8 @@ export const BLOCKING_RULES = [
         fix: "Pass `force: true` so it uploads without asking.",
     },
 ];
+/** `given`, with the fallback that keeps an older cached payload readable. */
+export const argsGiven = (action) => action.given ?? Object.keys(action.args);
 /**
  * Applies the table to the actions a lane calls.
  *

package/dist/src/heuristics/env-example.js

@@ -0,0 +1,36 @@
+/**
+ * The variable names a `.env.example` advertises.
+ *
+ * A project that keeps its variables in `fastlane/.env` almost always commits a
+ * `.env.example` beside it — that is what the file is *for*: telling whoever
+ * clones the repository which variables they need. It is the one manifest of
+ * required variables that is both conventional and, unlike `.env` itself,
+ * actually present in the clone a build runs from.
+ *
+ * It catches what parsing the Fastfile cannot. `SENTRY_AUTH_TOKEN` is read by
+ * `sentry-cli`, not by any `ENV.fetch` in a lane, so no amount of reading the
+ * Fastfile finds it — and it sits in `.env.example`, named, all along.
+ *
+ * Only names are taken. The file is an example by definition, so its values are
+ * placeholders; reading them would be reading fiction, and a checklist that
+ * compared them to anything would be worse than one that did not look.
+ */
+export function parseEnvExample(content) {
+    const names = [];
+    for (const raw of content.split("\n")) {
+        const line = raw.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        // `export FOO=bar` is legal in these files and means the same thing.
+        const assignment = line.replace(/^export\s+/, "");
+        const eq = assignment.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const name = assignment.slice(0, eq).trim();
+        // Shell-ish variable names only: anything else is a line this has
+        // misunderstood, and inventing a requirement is worse than missing one.
+        if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            names.push(name);
+    }
+    return [...new Set(names)];
+}

package/dist/src/heuristics/platforms.js

@@ -1,17 +1,76 @@
+import { join } from "node:path";
 /**
- * Which platforms a project builds for.
+ * Where to look for the markers, given where the Fastfile turned out to be.
  *
- * Named knowledge of mobile toolchains — that `.xcodeproj` means Xcode, that
- * `build.gradle` means Gradle — hence its place in this module, and the
- * boundary that comes with it: nothing here refuses anything. It answers a
- * question; `setup` writes the answer down and the checklist reads it.
+ * Two places, and the order does not matter because the answer is a union.
  *
- * It lives here rather than in `cli/detect.ts` because two callers need the
- * same answer. Setup proposes a configuration from it, and the checklist
- * decides which sections apply from it. Two copies of this reasoning would be
- * free to disagree about the same repository, and the checklist would be the
- * one that looked wrong.
+ * The repository root is the obvious one, and used to be the only one. It is
+ * wrong on its own: the markers sit *beside* an app's fastlane folder, not
+ * beside the repository root — `ios/Runner.xcodeproj` and `fastlane/` are
+ * siblings, and both move together when the app is one directory of a
+ * monorepo. A repository holding `app/fastlane/Fastfile` and
+ * `app/ios/Runner.xcodeproj` reported "no Xcode project and no Gradle build",
+ * because that is three levels down and the table reaches two.
+ *
+ * The app's own directory is the second, and it is the one laneyard already
+ * knows: it asked where the Fastfile was during setup. Between them they cover
+ * the arrangements that actually occur —
+ *
+ * - `fastlane/` and `*.xcodeproj` both at the root: a plain native app;
+ * - `fastlane/`, `ios/`, `android/` at the root: React Native, Flutter;
+ * - `app/fastlane/`, `app/ios/`, `app/android/`: the same app inside a monorepo;
+ * - `ios/fastlane/`: a fastlane set up for one platform only, which then
+ *   reports that one platform and not its sibling — right, since those lanes
+ *   build one platform, and an irrelevant section is what teaches someone to
+ *   ignore the screen.
+ *
+ * Keeping both roots rather than replacing one with the other is what makes
+ * this strictly an addition: nothing the old behaviour found is lost.
+ *
+ * What is deliberately *not* done is deepening the table to `*​/*​/*` or `**`.
+ * A third level would match `node_modules/some-package/ios/X.xcodeproj` and
+ * `app/ios/Pods/Pods.xcodeproj`, and report iOS for an Android-only project on
+ * the strength of a dependency's own Xcode project. `**` would do that and walk
+ * every build directory to do it. Two levels from a root that is actually the
+ * app is a better question than four levels from a root that is not.
+ */
+export function appRootOf(fastlaneDir) {
+    if (!fastlaneDir)
+        return ".";
+    // Repository-relative and always forward-slashed, whatever the platform.
+    const parent = fastlaneDir.replace(/\/+$/, "").split("/").slice(0, -1).join("/");
+    return parent === "" ? "." : parent;
+}
+/**
+ * The one directory to list, given where the Fastfile turned out to be.
+ *
+ * Not the repository root, which is what it used to be and what made a
+ * repository holding `app/fastlane/Fastfile` and `app/ios/Runner.xcodeproj`
+ * report "no Xcode project and no Gradle build": that is three levels down and
+ * the table reaches two.
+ *
+ * Not both, either, though that was tempting — keeping the root as well would
+ * have made this purely additive. It also means a project configured with
+ * `ios/fastlane` is shown the Android section, on the strength of a sibling
+ * `android/` folder those lanes never touch. The fastlane directory is not a
+ * guess: setup asked for it and `laneyard.yml` records it, and it says which
+ * app this project *is*. Trusting it is the difference between a checklist
+ * about this project and a checklist about the repository it lives in.
+ *
+ * Anyone it gets wrong has the escape hatch the check itself names: `platforms`
+ * in `laneyard.yml` is read first and skips all of this.
+ *
+ * What is deliberately not done is deepening the table to `*​/*​/*` or `**`. A
+ * third level matches `node_modules/some-package/ios/X.xcodeproj` and
+ * `app/ios/Pods/Pods.xcodeproj`, and would report iOS for an Android-only
+ * project on the strength of a dependency. Two levels from a directory that is
+ * actually the app beats four from one that is not.
  */
+export function searchDir(from, appRoot) {
+    if (!appRoot || appRoot === "." || appRoot.startsWith(".."))
+        return from;
+    return join(from, appRoot);
+}
 /**
  * What a repository looks like from the outside, as a table.
  *