vydanne 0.12.0 → 0.13.0

package/README.md

@@ -491,6 +491,26 @@ allowCrossStoreTerms: ["Apple"],
 
 `VYDANNE_ALLOW_CROSS_STORE=1` overrides the whole check for one run.
 
+### When the build number is not the commit count
+
+`releases` maps a store's build number back to a commit because the build number IS
+`git rev-list --count`. A repo can be forced off that and be unable to get back: ship from a long
+branch, squash it onto the release branch, and the count lands *below* build numbers already
+uploaded. Google Play reserves every versionCode it has ever been given, so those numbers cannot
+be freed and the only way past them is a constant added to the count.
+
+```js
+buildNumberOffset: 100,   // build number = git rev-list --count <commit> + 100
+```
+
+`releases` then resolves commits again and prints the offset it applied, on both stores. Leave it
+at 0 — the default — for every app that never had the accident.
+
+It is the one input here vydanne **cannot** verify. The count check validates an index against its
+own commit, which a wrong offset passes just as cleanly as a right one, so a bad value names a
+wrong commit with full confidence. It is refused unless it is an integer, and reported wherever it
+is used, but keeping it true is yours.
+
 ### Accessibility Nutrition Labels
 
 Every other thing vydanne writes is a *fact* about your app. This one is a **claim about its

package/SKILL.md

@@ -57,7 +57,7 @@ which user file was used, and whether the `.p8` is on disk.
 `{profile}` — selection only, never secrets) · `platforms` (iOS and macOS are SEPARATE) · `uiLocales`
 (auto-mapped to ASC codes) · `localeMap` · `metadataDir` · `screenshots` · `rating` · `ageRating` ·
 `privacy` · `iaps` · `previews` · `export` · `accessibility` · `ios` · `google` (Google Play) ·
-`bridge` · `push` · `reviewContact` · `allowCrossStoreTerms`.
+`bridge` · `push` · `reviewContact` · `allowCrossStoreTerms` · `buildNumberOffset`.
 
 **Paths are defaults, not laws.** `metadataDir` (default `fastlane/metadata`), `screenshots`
 (`{IOS, MAC_OS}`, default `fastlane/screenshots` + `-macos`) and `google.images` (Play image type →
@@ -316,7 +316,16 @@ names and whether it carries a **tag**. Both stores in this portfolio derive the
 `git rev-list --count HEAD` (Android's `versionCode`, iOS's `CURRENT_PROJECT_VERSION` via
 `Scripts/build-number.sh`), which makes it reversible.
 
-**Every mapping is verified, never assumed.** `rev-list --reverse` is ordered, not counted, so on a
+**`buildNumberOffset` when the count no longer matches.** A repo can be forced off the plain
+convention and be unable to get back: ship from a long branch, squash it onto the release branch,
+and the count lands BELOW versionCodes already uploaded — which Play reserves permanently, so a
+constant is the only way over them. `buildNumberOffset: 100` tells `releases` that
+`build = commits + 100`, and both commands print the offset they applied. It is the one number
+here vydanne cannot verify — the count check validates an index against its own commit and cannot
+tell a right offset from one wrong by five — so it is refused unless it is an integer, and stated
+wherever it is used rather than assumed.
+
+**Every other mapping is verified, never assumed.** `rev-list --reverse` is ordered, not counted, so on a
 merged history the Nth line need not be the commit with N ancestors — the candidate's own count has
 to match. An app that does not build this way, or a build number that is not a commit count, gets a
 stated reason instead of a confident wrong answer. That check has already caught a real one: a build

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vydanne",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "App Store Connect + Google Play submission prep — the companion to zdymak (media). Native Node (no fastlane/Ruby/Python): localized listings, screenshot/preview/icon upload, ratings, review contact, accessibility & privacy labels, IAP, export docs, build upload to TestFlight / a Play closed track, a diff of local-vs-store, and a preflight verifier that encodes the store gotchas. Never submits for review. iOS/macOS via the ASC REST API; Android via the Play Developer Edits API (--store google).",
   "keywords": [
     "app-store-connect",

package/src/buildCommit.mjs

@@ -10,7 +10,22 @@ import { execFileSync } from "node:child_process";
  * or reproducing a store binary needs the tree the archive was cut from, and a version string does
  * not identify one.
  *
- * ### Nothing here assumes the convention holds — it VERIFIES it, per build
+ * ### The offset, and what it costs
+ *
+ * `buildNumberOffset` shifts the relationship to `count + offset`, because a repo can be forced
+ * off the plain count and not be able to get back. Squash a long branch onto `master` after
+ * shipping from it and master's count lands BELOW build numbers already uploaded — and Google Play
+ * reserves every versionCode it has ever been given, so the only way over them is a constant.
+ *
+ * **The offset is a declaration this module cannot check**, and that is a real weakening worth
+ * stating rather than burying. The count check below verifies an INDEX against its own commit; it
+ * cannot tell a correct offset from one that is wrong by five, because the commit five places away
+ * verifies just as cleanly. So a wrong offset buys exactly the confident wrong answer everything
+ * else here exists to refuse. It is declared once per app, in a committed file, next to the script
+ * that stamps the number — and the commands say which offset they applied, so a reader can see the
+ * assumption instead of inheriting it.
+ *
+ * ### Nothing else here assumes the convention holds — it VERIFIES it, per build
  *
  * vydanne is pointed at apps that do not build this way, so a mapping that trusted the convention
  * would confidently name the wrong commit for them. Every answer below is checked
@@ -59,12 +74,20 @@ export function tagsAt(sha) {
  * Returns `{ sha }` when the count checks out, or `{ why }` naming what stopped it — which is the
  * useful half. "This build has no commit" is a finding about the release, not a gap in the tool.
  */
-export function commitForBuild(order, build) {
-  const n = Number(build);
+export function commitForBuild(order, build, offset = 0) {
+  const raw = Number(build);
   if (!order) return { why: "not a git checkout" };
-  if (!Number.isInteger(n) || n < 1) return { why: `build "${build}" is not a number` };
+  if (!Number.isInteger(raw)) return { why: `build "${build}" is not a number` };
+  // Every message below quotes the arithmetic when an offset is in play. A misconfigured offset
+  // surfaces here first, as a build that is impossibly far past HEAD, and "490 - 100 = 390, past
+  // HEAD (200 commits)" says which of the two numbers to go and look at.
+  const n = raw - offset;
+  const shown = offset ? `build ${raw} - offset ${offset} = ${n}` : `build ${n}`;
+  if (n < 1) {
+    return { why: `${shown} is below the first commit — the offset is larger than the build number` };
+  }
   if (n > order.length) {
-    return { why: `build ${n} is past HEAD (${order.length} commits) — built elsewhere, or on an unmerged branch` };
+    return { why: `${shown} is past HEAD (${order.length} commits) — built elsewhere, or on an unmerged branch` };
   }
   const sha = order[n - 1];
   let count;

package/src/commands/releases.mjs

@@ -42,6 +42,10 @@ export async function run(config, client) {
 
   const order = commitOrder();
   if (!order) console.log(yellow("  not a git checkout — commit and tag columns unavailable"));
+  // Said once, not per row: the commit column is only as true as this number, and a reader who
+  // does not know it was applied has no way to tell a mapping from an assumption.
+  const offset = config.buildNumberOffset || 0;
+  if (order && offset) console.log(`  commit column assumes buildNumberOffset=${offset} (build = commits + ${offset})`);
 
   // Newest first: the question is almost always about the last one or two.
   versions.sort((a, b) => String(b.attributes.createdDate).localeCompare(String(a.attributes.createdDate)));
@@ -71,7 +75,7 @@ export async function run(config, client) {
     } else if (backwards) {
       note = yellow(backwards);
     } else {
-      const got = commitForBuild(order, build);
+      const got = commitForBuild(order, build, offset);
       if (got.sha) {
         commit = got.sha.slice(0, 9);
         const tags = tagsAt(got.sha);

package/src/config.mjs

@@ -8,11 +8,26 @@ import { DEFAULT_PLAY_IMAGES } from "./play/images.mjs";
 
 // The public config surface — the drift guards assert each key is documented (README/SKILL) and typed
 // (types/index.d.ts). Add a config knob → document + type it, or the guards fail before publish.
-export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "localeMap", "metadataDir", "screenshots", "rating", "ageRating", "categories", "contentRights", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility", "bridge", "push", "reviewContact", "allowCrossStoreTerms"];
+export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "localeMap", "metadataDir", "screenshots", "rating", "ageRating", "categories", "contentRights", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility", "bridge", "push", "reviewContact", "allowCrossStoreTerms", "buildNumberOffset"];
 
 // One `vydanne.config.mjs` per app (ESM, like zdymak.config.mjs) — nothing hard-coded. Secrets stay out:
 // credentials resolve from the environment, a gitignored .env, or ~/.appstoreconnect/config.json (see
 // credentials.mjs) and are REFUSED if found in this committed file; review-contact PII stays gitignored.
+/**
+ * An integer config value, or the default when absent — and a refusal when it is neither.
+ *
+ * `buildNumberOffset: "100"` would otherwise coerce through the arithmetic and shift every commit
+ * lookup by a string, which resolves to a real commit and reports it with no hint anything is
+ * wrong. A value this load-bearing is worth one type check.
+ */
+function integerOr(name, value, fallback) {
+  if (value == null) return fallback;
+  if (!Number.isInteger(value)) {
+    throw new Error(`vydanne: config '${name}' must be an integer, got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
 export async function loadConfig(p) {
   const file = path.resolve(p || process.env.VYDANNE_CONFIG || "vydanne.config.mjs");
   if (!fs.existsSync(file)) throw new Error(`vydanne: config not found at ${file}`);
@@ -71,6 +86,13 @@ export async function loadConfig(p) {
     bridge: raw.bridge
       ? { out: raw.bridge.out || null, apple: raw.bridge.apple || null, play: raw.bridge.play || null }
       : null,
+    // `build number = git rev-list --count <commit> + buildNumberOffset`, for a repo that was
+    // forced off the plain count and cannot get back — squash a long branch onto the release
+    // branch after shipping from it and the count lands below versionCodes already spent, which
+    // Play reserves forever. Unlike everything else in buildCommit.mjs this is a DECLARATION the
+    // tool cannot verify, so it is refused unless it is an integer and reported wherever it is
+    // applied. 0 means the plain convention, which is every app that never had the accident.
+    buildNumberOffset: integerOr("buildNumberOffset", raw.buildNumberOffset, 0),
     // Terms the cross-store check must not flag for this app (see src/crossStore.mjs).
     allowCrossStoreTerms: raw.allowCrossStoreTerms || [],
     previews: raw.previews || null,

package/src/play/commands/releases.mjs

@@ -41,6 +41,10 @@ export async function run(config, client) {
 
   const order = commitOrder();
   if (!order) console.log(yellow("  not a git checkout — commit and tag columns unavailable"));
+  // Said once, not per row: the commit column is only as true as this number, and a reader who
+  // does not know it was applied has no way to tell a mapping from an assumption.
+  const offset = config.buildNumberOffset || 0;
+  if (order && offset) console.log(`  commit column assumes buildNumberOffset=${offset} (versionCode = commits + ${offset})`);
 
   const editId = await client.newEdit();
   let uploaded = [];
@@ -92,7 +96,7 @@ export async function run(config, client) {
       let commit = "-";
       let tag = "-";
       let note = "";
-      const got = commitForBuild(order, row.code);
+      const got = commitForBuild(order, row.code, offset);
       if (got.sha) {
         commit = got.sha.slice(0, 9);
         const tags = tagsAt(got.sha);

package/types/index.d.ts

@@ -343,6 +343,18 @@ export interface VydanneConfig {
    * "apple"); it is not a way to ship a store name.
    */
   allowCrossStoreTerms?: string[];
+
+  /**
+   * `build number = git rev-list --count <commit> + buildNumberOffset`. Defaults to 0, which is
+   * the plain convention.
+   *
+   * Set it only for a repo that was forced off the plain count and cannot get back: ship from a
+   * long branch, squash that branch onto the release branch, and the count lands below build
+   * numbers already uploaded — which Google Play reserves permanently, so a constant is the only
+   * way over them. It is a declaration vydanne cannot verify, so keep it true; a wrong one names
+   * a wrong commit as confidently as a right one.
+   */
+  buildNumberOffset?: number;
 }
 
 /** Thin ASC REST client (native fetch + ES256 JWT). */