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

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`,
+    });
+  }
+}