@mmerterden/multi-agent-toolkit-mcp 3.9.0 → 3.12.0

package/tools/pass-kit/spec.js

@@ -0,0 +1,317 @@
+/**
+ * spec.js  -  what Apple requires of a pass, as data.
+ *
+ * Everything here is a table rather than a code path, because all of it is
+ * somebody else's specification and the only useful property is that it is easy
+ * to correct. Nothing in this file is tied to an airline, a brand or a project;
+ * the five styles are the five Apple defines.
+ *
+ * The enum lists matter more than they look. A single invalid
+ * `PKPassengerCapability*` value does not produce an error - Wallet silently
+ * declines to render the enhanced layout and the pass falls back to the old
+ * one, with nothing anywhere saying why. That failure mode is the reason this
+ * file exists at all.
+ *
+ * @module tools/pass-kit/spec
+ */
+
+export const STYLES = ["boardingPass", "coupon", "eventTicket", "generic", "storeCard"];
+
+/**
+ * Top-level keys every pass must carry, whatever its style.
+ * Apple rejects a pass missing any of these outright.
+ */
+export const REQUIRED_TOP_LEVEL = [
+  "description",
+  "formatVersion",
+  "organizationName",
+  "passTypeIdentifier",
+  "serialNumber",
+  "teamIdentifier",
+];
+
+/**
+ * Images, per style.
+ *
+ * `required` is what Wallet will not render without. `optional` is what the
+ * style can use. Anything outside both lists is dead weight in the manifest -
+ * worth reporting, because it is usually a naming mistake rather than a spare.
+ *
+ * Retina variants are implied: `logo` means logo.png, logo@2x.png, logo@3x.png,
+ * and the 1x file carries no suffix. That last detail is a real trap - a file
+ * named `footer@1x.png` is not the 1x footer, it is a file Wallet ignores.
+ */
+export const ASSETS = {
+  boardingPass: { required: ["icon", "logo"], optional: ["footer", "background", "thumbnail"] },
+  coupon: { required: ["icon", "logo"], optional: ["strip"] },
+  eventTicket: { required: ["icon", "logo"], optional: ["strip", "background", "thumbnail"] },
+  generic: { required: ["icon", "logo"], optional: ["thumbnail"] },
+  storeCard: { required: ["icon", "logo"], optional: ["strip"] },
+};
+
+/** Every image name a pass may legitimately contain, at any scale. */
+export const ALL_IMAGE_BASENAMES = [
+  "icon",
+  "logo",
+  "strip",
+  "background",
+  "thumbnail",
+  "footer",
+  "personalizationLogo",
+];
+
+export const SCALES = ["", "@2x", "@3x"];
+
+/** boardingPass carries one extra required key inside its style dictionary. */
+export const STYLE_REQUIRED_KEYS = {
+  boardingPass: ["transitType"],
+};
+
+export const TRANSIT_TYPES = [
+  "PKTransitTypeAir",
+  "PKTransitTypeBoat",
+  "PKTransitTypeBus",
+  "PKTransitTypeGeneric",
+  "PKTransitTypeTrain",
+];
+
+export const BARCODE_FORMATS = [
+  "PKBarcodeFormatQR",
+  "PKBarcodeFormatPDF417",
+  "PKBarcodeFormatAztec",
+  "PKBarcodeFormatCode128",
+];
+
+export const FIELD_BUCKETS = [
+  "headerFields",
+  "primaryFields",
+  "secondaryFields",
+  "auxiliaryFields",
+  "backFields",
+  // Newer than the other five and only meaningful on a boardingPass. Listed
+  // because a real, working, signed enhanced boarding pass uses it: reporting
+  // it as "a bucket Apple does not define" was this validator being wrong
+  // about somebody else's correct pass, which is worse than saying nothing.
+  "footerFields",
+];
+
+/**
+ * Enumerated semantic values.
+ *
+ * An unknown value in one of these is the quiet failure described in the file
+ * header: no error, no warning, and an enhanced pass that silently renders as a
+ * legacy one.
+ */
+export const SEMANTIC_ENUMS = {
+  passengerCapabilities: [
+    "PKPassengerCapabilityPreBoarding",
+    "PKPassengerCapabilityPriorityBoarding",
+    "PKPassengerCapabilityCarryon",
+    "PKPassengerCapabilityPersonalItem",
+  ],
+  departureLocationSecurityPrograms: [
+    "PKTransitSecurityProgramTSAPreCheck",
+    "PKTransitSecurityProgramGlobalEntry",
+    "PKTransitSecurityProgramClear",
+    "PKTransitSecurityProgramNexus",
+    "PKTransitSecurityProgramSentri",
+    "PKTransitSecurityProgramTSAPreCheckTouchlessID",
+    "PKTransitSecurityProgramFastTrack",
+  ],
+  eventType: [
+    "PKEventTypeGeneric",
+    "PKEventTypeLivePerformance",
+    "PKEventTypeMovie",
+    "PKEventTypeSports",
+    "PKEventTypeConference",
+    "PKEventTypeConvention",
+    "PKEventTypeWorkshop",
+    "PKEventTypeSocialGathering",
+  ],
+};
+
+SEMANTIC_ENUMS.destinationLocationSecurityPrograms =
+  SEMANTIC_ENUMS.departureLocationSecurityPrograms;
+SEMANTIC_ENUMS.passengerEligibleSecurityPrograms =
+  SEMANTIC_ENUMS.departureLocationSecurityPrograms;
+
+/**
+ * Semantic tags, by the type a validator can actually check.
+ *
+ * Not exhaustive of Apple's catalogue and not trying to be - it covers the
+ * shapes that are wrong often enough to be worth catching: a date that is not
+ * ISO 8601, a number sent as a string, a location missing a coordinate.
+ */
+export const SEMANTIC_TYPES = {
+  // Flight and transit
+  airlineCode: "string",
+  flightCode: "string",
+  flightNumber: "number",
+  departureAirportCode: "string",
+  departureAirportName: "string",
+  departureCityName: "string",
+  departureStationName: "string",
+  departurePlatform: "string",
+  departureLocationDescription: "string",
+  departureGate: "string",
+  departureTerminal: "string",
+  departureLocation: "location",
+  departureLocationTimeZone: "string",
+  destinationAirportCode: "string",
+  destinationAirportName: "string",
+  destinationCityName: "string",
+  destinationStationName: "string",
+  destinationPlatform: "string",
+  destinationLocationDescription: "string",
+  destinationGate: "string",
+  destinationTerminal: "string",
+  destinationLocation: "location",
+  destinationLocationTimeZone: "string",
+  boardingGroup: "string",
+  boardingSequenceNumber: "string",
+  boardingZone: "string",
+  originalBoardingDate: "date",
+  currentBoardingDate: "date",
+  originalDepartureDate: "date",
+  currentDepartureDate: "date",
+  originalArrivalDate: "date",
+  currentArrivalDate: "date",
+  transitProvider: "string",
+  transitStatus: "string",
+  transitStatusReason: "string",
+  vehicleName: "string",
+  vehicleNumber: "string",
+  vehicleType: "string",
+  carNumber: "string",
+  confirmationNumber: "string",
+  passengerName: "personName",
+  membershipProgramName: "string",
+  membershipProgramNumber: "string",
+  priorityStatus: "string",
+  ticketFareClass: "string",
+  securityScreening: "string",
+  membershipProgramStatus: "string",
+  internationalDocumentsAreVerified: "boolean",
+  internationalDocumentsVerifiedDeclarationName: "string",
+  passengerAirlineSSRs: "array",
+  passengerInformationSSRs: "array",
+  passengerServiceSSRs: "array",
+  loungePlaceIDs: "array",
+  wifiAccess: "array",
+  seats: "array",
+  // Event
+  eventName: "string",
+  eventType: "string",
+  eventStartDate: "date",
+  eventEndDate: "date",
+  venueName: "string",
+  venueLocation: "location",
+  venueRoom: "string",
+  venueEntrance: "string",
+  venueRegionName: "string",
+  venuePhoneNumber: "string",
+  venueOpenDate: "date",
+  venueDoorsOpenDate: "date",
+  venueGatesOpenDate: "date",
+  venueCloseDate: "date",
+  entranceDescription: "string",
+  admissionLevelAbbreviation: "string",
+  additionalTicketAttributes: "string",
+  tailgatingAllowed: "boolean",
+  admissionLevel: "string",
+  attendeeName: "string",
+  performerNames: "array",
+  genre: "string",
+  sportName: "string",
+  leagueName: "string",
+  leagueAbbreviation: "string",
+  homeTeamName: "string",
+  homeTeamAbbreviation: "string",
+  homeTeamLocation: "string",
+  awayTeamName: "string",
+  awayTeamAbbreviation: "string",
+  awayTeamLocation: "string",
+  artistIDs: "array",
+  albumIDs: "array",
+  playlistIDs: "array",
+  // General
+  totalPrice: "currency",
+  balance: "currency",
+  duration: "number",
+  silenceRequested: "boolean",
+};
+
+/**
+ * Keys renamed between iOS 18 and iOS 26.
+ *
+ * A pass carrying the old spelling is not rejected; the tag is ignored, which
+ * means the feature it drives silently does not appear.
+ */
+export const RENAMED_SEMANTICS = {
+  departureAirportTimeZone: "departureLocationTimeZone",
+  destinationAirportTimeZone: "destinationLocationTimeZone",
+  airlinePassengerCapabilities: "passengerCapabilities",
+};
+
+/**
+ * Semantic tags an enhanced boarding pass needs before Wallet will use the
+ * richer layout. Missing any of them is not an error - the pass simply renders
+ * the way it did before, which is exactly why it is worth reporting.
+ */
+export const ENHANCED_BOARDING_PASS_TAGS = [
+  "airlineCode",
+  "flightNumber",
+  "departureAirportCode",
+  "destinationAirportCode",
+  "originalDepartureDate",
+  "originalArrivalDate",
+  "originalBoardingDate",
+  "departureLocationTimeZone",
+  "destinationLocationTimeZone",
+];
+
+const ISO_8601 =
+  /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+
+/**
+ * @returns {string|null} why the value is wrong for its declared type
+ */
+export function checkSemanticValue(key, type, value) {
+  switch (type) {
+    case "string":
+      return typeof value === "string" ? null : `must be a string, got ${typeOf(value)}`;
+    case "number":
+      return typeof value === "number" && Number.isFinite(value)
+        ? null
+        : `must be a number, got ${typeOf(value)}`;
+    case "boolean":
+      return typeof value === "boolean" ? null : `must be a boolean, got ${typeOf(value)}`;
+    case "array":
+      return Array.isArray(value) ? null : `must be an array, got ${typeOf(value)}`;
+    case "date":
+      if (typeof value !== "string") return `must be an ISO 8601 string, got ${typeOf(value)}`;
+      return ISO_8601.test(value) ? null : `"${value}" is not ISO 8601`;
+    case "location":
+      if (!value || typeof value !== "object") return `must be an object with latitude and longitude`;
+      if (typeof value.latitude !== "number" || typeof value.longitude !== "number") {
+        return "latitude and longitude are both required and must be numbers";
+      }
+      return null;
+    case "currency":
+      if (!value || typeof value !== "object") return "must be an object";
+      if (typeof value.currencyCode !== "string") return "currencyCode is required";
+      if (typeof value.amount !== "string") return "amount must be a STRING, not a number";
+      return null;
+    case "personName":
+      if (!value || typeof value !== "object") return "must be an object of name components";
+      return null;
+    default:
+      return null;
+  }
+}
+
+function typeOf(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  return typeof v;
+}

package/tools/pass-kit/validate.js

@@ -0,0 +1,329 @@
+/**
+ * validate.js  -  every check that can be made without signing anything.
+ *
+ * Pure: it takes a parsed pass.json and a list of file names, and returns
+ * findings. No I/O, so it is the same function whether it is checking a draft
+ * before a build or an existing `.pkpass` after one.
+ *
+ * Findings are graded because the consequences genuinely differ:
+ *
+ *   error    Wallet refuses the pass, or the pass is wrong about itself.
+ *   warning  Wallet accepts it and quietly does less than intended - the
+ *            enhanced layout falls back, a localized string never resolves, a
+ *            renamed tag is ignored. This grade is the point of the file.
+ *   note     Harmless, but somebody meant something by it.
+ *
+ * @module tools/pass-kit/validate
+ */
+
+import {
+  STYLES,
+  REQUIRED_TOP_LEVEL,
+  ASSETS,
+  ALL_IMAGE_BASENAMES,
+  STYLE_REQUIRED_KEYS,
+  TRANSIT_TYPES,
+  BARCODE_FORMATS,
+  FIELD_BUCKETS,
+  SEMANTIC_ENUMS,
+  SEMANTIC_TYPES,
+  RENAMED_SEMANTICS,
+  ENHANCED_BOARDING_PASS_TAGS,
+  checkSemanticValue,
+} from "./spec.js";
+
+const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
+const RGB_COLOR = /^rgb\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*\)$/;
+
+/**
+ * @param {object} pass       parsed pass.json
+ * @param {string[]} files    file names present beside it, e.g. ["icon.png", "en.lproj/pass.strings"]
+ * @param {object} [opts]
+ * @returns {{style: string|null, errors: object[], warnings: object[], notes: object[], ok: boolean}}
+ */
+export function validatePass(pass, files = [], opts = {}) {
+  const errors = [];
+  const warnings = [];
+  const notes = [];
+  const add = (list, where, message) => list.push({ where, message });
+
+  if (!pass || typeof pass !== "object") {
+    return { style: null, errors: [{ where: "pass.json", message: "not a JSON object" }], warnings, notes, ok: false };
+  }
+
+  for (const key of REQUIRED_TOP_LEVEL) {
+    if (pass[key] === undefined || pass[key] === "") add(errors, key, "required top-level key is missing");
+  }
+  if (pass.formatVersion !== undefined && pass.formatVersion !== 1) {
+    add(errors, "formatVersion", `must be 1, got ${JSON.stringify(pass.formatVersion)}`);
+  }
+
+  const present = STYLES.filter((s) => pass[s] !== undefined);
+  let style = null;
+  if (present.length === 0) {
+    add(errors, "pass.json", `no style dictionary: exactly one of ${STYLES.join(", ")} is required`);
+  } else if (present.length > 1) {
+    add(errors, "pass.json", `${present.length} style dictionaries (${present.join(", ")}); a pass has exactly one`);
+  } else {
+    style = present[0];
+  }
+
+  if (style) {
+    const body = pass[style] || {};
+    for (const key of STYLE_REQUIRED_KEYS[style] || []) {
+      if (body[key] === undefined) add(errors, `${style}.${key}`, "required for this style");
+    }
+    if (style === "boardingPass" && body.transitType && !TRANSIT_TYPES.includes(body.transitType)) {
+      add(errors, "boardingPass.transitType", `"${body.transitType}" is not one of ${TRANSIT_TYPES.join(", ")}`);
+    }
+    for (const bucket of Object.keys(body)) {
+      if (!FIELD_BUCKETS.includes(bucket) && bucket !== "transitType") {
+        add(notes, `${style}.${bucket}`, "not a field bucket Apple defines; it will be ignored");
+      }
+    }
+    for (const bucket of FIELD_BUCKETS) {
+      const rows = body[bucket];
+      if (rows === undefined) continue;
+      if (!Array.isArray(rows)) {
+        add(errors, `${style}.${bucket}`, "must be an array");
+        continue;
+      }
+      rows.forEach((f, i) => {
+        const at = `${style}.${bucket}[${i}]`;
+        if (!f || typeof f !== "object") return add(errors, at, "must be an object");
+        if (typeof f.key !== "string" || !f.key) add(errors, at, "`key` is required");
+        if (f.value === undefined) add(errors, at, "`value` is required");
+      });
+    }
+  }
+
+  checkColors(pass, errors);
+  checkBarcodes(pass, errors, warnings);
+  checkSemantics(pass, style, errors, warnings, notes, opts);
+  checkWebService(pass, errors, warnings);
+  checkAssets(style, files, errors, warnings, notes);
+  checkLocalization(pass, style, files, warnings);
+  checkLabels(pass, style, files, warnings);
+
+  return { style, errors, warnings, notes, ok: errors.length === 0 };
+}
+
+function checkColors(pass, errors) {
+  for (const key of ["foregroundColor", "backgroundColor", "labelColor", "stripColor"]) {
+    const v = pass[key];
+    if (v === undefined) continue;
+    if (typeof v !== "string" || (!HEX_COLOR.test(v) && !RGB_COLOR.test(v))) {
+      errors.push({ where: key, message: `must be #RRGGBB or rgb(r,g,b), got ${JSON.stringify(v)}` });
+    }
+  }
+}
+
+function checkBarcodes(pass, errors, warnings) {
+  const list = pass.barcodes;
+  if (list === undefined) {
+    if (pass.barcode === undefined) {
+      warnings.push({ where: "barcodes", message: "no barcode: the pass will scan nowhere" });
+    }
+    return;
+  }
+  if (!Array.isArray(list)) return errors.push({ where: "barcodes", message: "must be an array" });
+  list.forEach((b, i) => {
+    const at = `barcodes[${i}]`;
+    if (!b || typeof b !== "object") return errors.push({ where: at, message: "must be an object" });
+    if (!BARCODE_FORMATS.includes(b.format)) {
+      errors.push({ where: `${at}.format`, message: `"${b.format}" is not one of ${BARCODE_FORMATS.join(", ")}` });
+    }
+    if (typeof b.message !== "string" || !b.message) {
+      errors.push({ where: `${at}.message`, message: "required" });
+    }
+    if (typeof b.messageEncoding !== "string" || !b.messageEncoding) {
+      errors.push({ where: `${at}.messageEncoding`, message: 'required, usually "iso-8859-1"' });
+    }
+  });
+}
+
+function checkSemantics(pass, style, errors, warnings, notes, opts) {
+  // Semantics live at the top level and may also appear per field. Both are
+  // checked; the top-level block is the one the enhanced layouts read.
+  const blocks = [{ at: "semantics", value: pass.semantics }];
+  if (style && pass[style]) {
+    for (const bucket of FIELD_BUCKETS) {
+      (pass[style][bucket] || []).forEach((f, i) => {
+        if (f && f.semantics) blocks.push({ at: `${style}.${bucket}[${i}].semantics`, value: f.semantics });
+      });
+    }
+  }
+
+  for (const { at, value } of blocks) {
+    if (value === undefined) continue;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      errors.push({ where: at, message: "must be an object" });
+      continue;
+    }
+    for (const [key, v] of Object.entries(value)) {
+      const renamedTo = RENAMED_SEMANTICS[key];
+      if (renamedTo) {
+        warnings.push({
+          where: `${at}.${key}`,
+          message: `renamed to "${renamedTo}" in iOS 26. The old spelling is not rejected, it is ignored - so whatever it drives silently does not appear`,
+        });
+        continue;
+      }
+      const allowed = SEMANTIC_ENUMS[key];
+      if (allowed) {
+        const values = Array.isArray(v) ? v : [v];
+        for (const one of values) {
+          if (!allowed.includes(one)) {
+            errors.push({
+              where: `${at}.${key}`,
+              message: `"${one}" is not a value Apple defines. One unknown value here does not raise an error: Wallet declines the enhanced layout and falls back silently. Allowed: ${allowed.join(", ")}`,
+            });
+          }
+        }
+        continue;
+      }
+      const type = SEMANTIC_TYPES[key];
+      if (!type) {
+        notes.push({ where: `${at}.${key}`, message: "not a semantic tag this validator knows; it may be new or misspelled" });
+        continue;
+      }
+      const bad = checkSemanticValue(key, type, v);
+      if (bad) errors.push({ where: `${at}.${key}`, message: bad });
+    }
+  }
+
+  const top = pass.semantics || {};
+  // `original*` is the schedule and `current*` is the live value. Rewriting
+  // `original*` on an update destroys the only record of what changed, which is
+  // what the delay notifications are computed from.
+  for (const pair of [
+    ["originalDepartureDate", "currentDepartureDate"],
+    ["originalArrivalDate", "currentArrivalDate"],
+    ["originalBoardingDate", "currentBoardingDate"],
+  ]) {
+    if (top[pair[1]] !== undefined && top[pair[0]] === undefined) {
+      warnings.push({
+        where: `semantics.${pair[1]}`,
+        message: `set without ${pair[0]}. The original is the schedule and the current is the live value; with no original there is nothing to compare against`,
+      });
+    }
+  }
+
+  if (style === "boardingPass" && opts.enhanced !== false) {
+    const missing = ENHANCED_BOARDING_PASS_TAGS.filter((t) => top[t] === undefined);
+    if (missing.length && missing.length < ENHANCED_BOARDING_PASS_TAGS.length) {
+      warnings.push({
+        where: "semantics",
+        message: `an enhanced boarding pass wants ${missing.length} more tag(s): ${missing.join(", ")}. Missing them is not an error - the pass renders the older layout instead, with nothing saying why`,
+      });
+    }
+  }
+}
+
+function checkWebService(pass, errors, warnings) {
+  const hasUrl = typeof pass.webServiceURL === "string" && pass.webServiceURL !== "";
+  const hasToken = typeof pass.authenticationToken === "string" && pass.authenticationToken !== "";
+  if (hasUrl !== hasToken) {
+    errors.push({
+      where: hasUrl ? "authenticationToken" : "webServiceURL",
+      message: "webServiceURL and authenticationToken go together; one without the other disables updates",
+    });
+  }
+  if (hasUrl && !/^https:\/\//i.test(pass.webServiceURL)) {
+    errors.push({ where: "webServiceURL", message: "must be https" });
+  }
+  if (hasToken && pass.authenticationToken.length < 16) {
+    warnings.push({
+      where: "authenticationToken",
+      message: "shorter than 16 characters; Apple requires at least 16",
+    });
+  }
+}
+
+function checkAssets(style, files, errors, warnings, notes) {
+  if (!style) return;
+  const names = new Set(files.map((f) => f.split("/").pop()));
+  const has = (base) => names.has(`${base}.png`) || names.has(`${base}@2x.png`) || names.has(`${base}@3x.png`);
+  const contract = ASSETS[style] || { required: [], optional: [] };
+
+  for (const base of contract.required) {
+    if (!has(base)) {
+      // Tagged, because the pass.json-only caller has no files to check and has
+      // to drop these. It used to drop them by matching the message text, which
+      // stops working the moment the wording is improved - silently, and in the
+      // direction of reporting missing images that were never claimed present.
+      errors.push({ where: `${base}.png`, message: `required for a ${style}`, kind: "asset" });
+    }
+  }
+  for (const base of ALL_IMAGE_BASENAMES) {
+    if (!has(base)) continue;
+    if (contract.required.includes(base) || contract.optional.includes(base)) continue;
+    notes.push({ where: `${base}.png`, message: `a ${style} does not use this image; it is weight in the manifest` });
+  }
+  // The 1x file carries NO suffix. `footer@1x.png` is not the 1x footer - it is
+  // a file Wallet never looks for, hashed into the manifest for nothing.
+  for (const n of names) {
+    if (/@1x\.png$/.test(n)) {
+      warnings.push({
+        where: n,
+        message: `the 1x variant has no suffix. Wallet looks for "${n.replace("@1x", "")}" and will not find this file`,
+      });
+    }
+  }
+  for (const base of contract.required) {
+    if (has(base) && !names.has(`${base}@2x.png`)) {
+      notes.push({ where: `${base}@2x.png`, message: "no @2x variant; it will be upscaled on every modern device" });
+    }
+  }
+}
+
+function checkLocalization(pass, style, files, warnings) {
+  const lprojs = new Set(
+    files.filter((f) => f.includes(".lproj/")).map((f) => f.split(".lproj/")[0].split("/").pop()),
+  );
+  if (lprojs.size === 0) return;
+  const strings = new Set(files.filter((f) => f.endsWith(".lproj/pass.strings")).map((f) => f.split(".lproj/")[0].split("/").pop()));
+  for (const l of lprojs) {
+    if (!strings.has(l)) {
+      warnings.push({ where: `${l}.lproj`, message: "no pass.strings; every label in this language falls back" });
+    }
+  }
+}
+
+/**
+ * Labels, which are the quietest way a pass ends up half-translated.
+ *
+ * Deliberately NOT inside checkLocalization: this first lived there, behind its
+ * early return, and therefore never ran on a pass with no .lproj folder at all -
+ * which is the case where a key-shaped label is worst, because it renders as the
+ * key. A test caught it.
+ */
+function checkLabels(pass, style, files, warnings) {
+  if (!style || !pass[style]) return;
+  const labels = [];
+  for (const bucket of FIELD_BUCKETS) {
+    (pass[style][bucket] || []).forEach((f) => {
+      if (f && typeof f.label === "string" && f.label) labels.push(f.label);
+    });
+  }
+  if (labels.length === 0) return;
+
+  const keyish = labels.filter((l) => /^[a-z][A-Za-z0-9_]*$/.test(l) || /_/.test(l));
+  const hasStrings = files.some((f) => f.endsWith(".lproj/pass.strings"));
+
+  if (keyish.length > 0 && !hasStrings) {
+    warnings.push({
+      where: `${style} labels`,
+      message: `${keyish.length} label(s) look like localization keys (${keyish.slice(0, 4).map((l) => JSON.stringify(l)).join(", ")}) but no .lproj/pass.strings was found. An unresolved key renders as the key itself`,
+    });
+    return;
+  }
+
+  if (labels.length >= 2 && keyish.length > 0 && keyish.length < labels.length) {
+    const literals = labels.filter((l) => !keyish.includes(l)).slice(0, 4);
+    warnings.push({
+      where: `${style} labels`,
+      message: `${keyish.length} of ${labels.length} labels look like localization keys and the rest look like literal text (e.g. ${literals.map((l) => JSON.stringify(l)).join(", ")}). Mixed labels localize the keys and leave the literals in one language`,
+    });
+  }
+}