@rightkit/release 0.6.16 → 0.6.20

package/snapshot-request.mjs

@@ -294,7 +294,10 @@ const lstatOrNull = (p) => { try { return fs.lstatSync(p); } catch (e) { if (e.c
  * `..` or empty component, not inside `.git`) and no input that is, or holds, either declaration file. A present but invalid canonical declaration is an
  * error: it is never read as the legacy one.
  */
-export function readDeclaredInputs(snapshotRoot) {
+/** Host platform names a declared input may scope itself to (`{ path, platforms }`). */
+export const DECLARED_INPUT_PLATFORMS = Object.freeze({ darwin: "mac", win32: "win", linux: "linux" });
+
+export function readDeclaredInputs(snapshotRoot, { platform = process.platform } = {}) {
   let file = null; let at = null; let meta = null;
   for (const candidate of COMPILE_INPUT_DECLARATIONS) {
     let here = snapshotRoot; let found = true;
@@ -313,8 +316,21 @@ export function readDeclaredInputs(snapshotRoot) {
   let value;
   try { value = JSON.parse(fs.readFileSync(at, "utf8")); } catch (e) { fail("declared-inputs", `${file} is not JSON (${e.message})`); }
   if (!value || typeof value !== "object" || !Array.isArray(value.inputs)) fail("declared-inputs", `${file}: \`inputs\` must be a list of paths`);
-  for (const input of value.inputs) {
+  // An entry is a path (every platform) or { path, platforms }: a platform-scoped input (a Windows-only identity package) is declared
+  // only on the hosts it names, so another host neither requires nor digests it. Unknown keys or platform names refuse.
+  const host = DECLARED_INPUT_PLATFORMS[platform] ?? platform;
+  const kept = [];
+  for (const entry of value.inputs) {
+    let input = entry;
+    if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+      const extra = Object.keys(entry).filter((k) => k !== "path" && k !== "platforms");
+      if (extra.length) fail("declared-inputs", `${file}: an input object has only path and platforms (found ${extra.join(", ")})`);
+      const names = Object.values(DECLARED_INPUT_PLATFORMS);
+      if (!Array.isArray(entry.platforms) || !entry.platforms.length || entry.platforms.some((x) => !names.includes(x))) fail("declared-inputs", `${file}: ${JSON.stringify(entry.path)}: platforms must be a non-empty list of ${names.join(", ")}`);
+      input = entry.path;
+    }
     if (typeof input !== "string" || !input) fail("declared-inputs", `${file}: every input is a non-empty relative path`);
+    const here = !(entry && typeof entry === "object") || entry.platforms.includes(host);
     const components = input.split(/[\\/]/);
     if (path.isAbsolute(input) || path.posix.isAbsolute(input) || path.win32.isAbsolute(input) || components.some((c) => c === "" || c === "." || c === "..")) fail("declared-inputs", `${file}: ${input} is not a plain relative path inside the snapshot`);
     if (components.some((c) => c.toLowerCase() === ".git")) fail("declared-inputs", `${file}: ${input} is inside .git; repository metadata is never a compile input`);
@@ -322,8 +338,9 @@ export function readDeclaredInputs(snapshotRoot) {
       const parts = declaration.split("/");
       if (components.length <= parts.length && components.every((c, i) => c === parts[i])) fail("declared-inputs", `${file}: ${input} overlaps the declaration file itself (${declaration})`);
     }
+    if (here) kept.push(input);
   }
-  return [...value.inputs];
+  return kept;
 }
 
 /** The inputs a request supplied must be exactly the declaration the snapshot holds (the broker's check): a throw naming the difference. */

package/snapshot.mjs

@@ -27,8 +27,8 @@
 // unreadable processes, build-ownership.mjs).
 //
 // Exclusion: one sync per snapshot at a time (`<root>/<repo-key>.lock`, re-checked before every write and before the verdict).
-// It narrows, but cannot close, the window in which two processes both replace one stale lock; host-wide build ownership held
-// from before the sync through the stage (joint plan step 4) is the exclusion builds rely on, and the broker re-verifies the tree.
+// It narrows, but cannot close, the window in which two processes both replace one stale lock; the per-repository build ownership
+// record held from before the sync through the stage (joint plan step 4) closes it, and the broker re-verifies the tree.
 
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -543,6 +543,13 @@ function inspectSnapshot({ dir, entries, checkout, platform = process.platform,
   }
   // Every candidate, ledger or new, must be ignored by the commit's own rules, as the neutral oracle judges them.
   const ignored = neutralIgnored(dir, candidates.map((c) => c.path));
+  // Git's own semantics for a directory: `git status` shows nothing for one whose every entry is ignored (or that holds nothing), even
+  // when no rule names the directory itself (a root rule `src-tauri/gen/schemas/` leaves `src-tauri/gen` unnamed). Judged deepest
+  // first, so a directory counts as ignored exactly when every file and subdirectory below it does; a single unignored file still refuses.
+  for (const d of candidates.filter((c) => c.type === "dir" && !ignored.has(c.path)).sort((a, b) => b.path.length - a.path.length)) {
+    const below = candidates.filter((c) => c.path.startsWith(`${d.path}/`));
+    if (below.every((c) => ignored.has(c.path))) ignored.add(d.path);
+  }
   for (const c of candidates) if (!ignored.has(c.path)) return problem(`${c.path} is not in the commit's tree and is not ignored by the commit's own ignore rules (the checkout's info/exclude and global excludes do not count)`);
   return { problem: null, admitted: [...candidates].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) };
 }
@@ -942,11 +949,11 @@ export function snapshotCommand(o, args, deps = {}) {
     // The managed root exists (the gate never creates it) and the root is private, BEFORE build ownership is taken: taking it
     // creates directories of its own, and must never be what brings a missing managed root into being.
     guardRoot(root, managedRoot, { device: o.device });
-    // A sync replaces snapshot bytes, so it runs only under the host's build ownership, taken before the first write (joined when
+    // A sync replaces snapshot bytes, so it runs only under the repository's build ownership, taken before the first write (joined when
     // this gate already holds it); a verify only reads.
     if (!verify) {
       const repo = repositoryOf(o.cwd);
-      ownership = (o.acquireOwnership ?? acquireBuildOwnership)({ file: ownershipFile({ platform: o.platform, beside: o.snapshotRoot }), stage: "snapshot", snapshot: path.join(root, repo.key), commit: resolveCommit(repo.checkout, rev).commit, platform: o.platform, env: o.env });
+      ownership = (o.acquireOwnership ?? acquireBuildOwnership)({ file: ownershipFile({ platform: o.platform, beside: o.snapshotRoot, repository: repo.key }), stage: "snapshot", snapshot: path.join(root, repo.key), commit: resolveCommit(repo.checkout, rev).commit, platform: o.platform, env: o.env });
     }
     const r = verify ? verifySnapshot({ checkout: o.cwd, rev, root, managedRoot, device: o.device, ...(envAt >= 0 ? { environment: { expected: args[envAt + 1], compute: deps.environmentDigest } } : {}) })
       : syncSnapshot({ checkout: o.cwd, rev, root, managedRoot, device: o.device });

package/stage-commands.mjs

@@ -41,7 +41,8 @@ export function expectedStageCommands({ kind, unit, config, manifest, platform }
   const pack = [];
   if (kind === "npm") {
     // The swap helper builds and signs a binary into its own directory of the snapshot (a declared stage output), then packs from there like any unit.
-    if (unit === SWAP_HELPER_PACKAGE) pack.push(CARGO(".", SWAP_HELPER_CARGO_ARGS), CARGO(".", SWAP_HELPER_METADATA_ARGS));
+    // A Linux direct origin builds none: the helper is built and signed hosted (publish.yml build-swap/sign-swap).
+    if (unit === SWAP_HELPER_PACKAGE && platform !== "linux") pack.push(CARGO(".", SWAP_HELPER_CARGO_ARGS), CARGO(".", SWAP_HELPER_METADATA_ARGS));
     pack.push(PNPM(npmPackArgs(dir, ANY_ABSOLUTE_PATH)));
   } else {
     compile.unshift(CARGO(crateDir, qualifyFmtArgs(unit)));

package/stage-ledger.mjs

@@ -148,6 +148,21 @@ export function attributionProblems({ before, after, reported, receipt }) {
   return problems;
 }
 
+/**
+ * The attribution of a step that reports no file list (an app's web build, `right-release web-build`): the declared compile inputs
+ * (`.rightkit/compile-inputs.json`) are the only paths it may write, so every path it added or changed must lie under one of them and
+ * nothing may be removed. Anything else is an unattributed write. `declared` are snapshot-relative posix paths.
+ */
+export function declaredOutputProblems({ before, after, declared }) {
+  const d = diffEntries(before, after);
+  const roots = declared.map((x) => x.replaceAll("\\", "/").replace(/\/+$/, ""));
+  const under = (p) => roots.some((r) => p === r || p.startsWith(`${r}/`));
+  const problems = [];
+  for (const p of [...d.added, ...d.changed]) if (!under(p)) problems.push(`${p} was written by the web build but lies under no declared compile input`);
+  for (const p of d.removed) problems.push(`${p} was removed by the web build`);
+  return problems;
+}
+
 /** Every `path` string a staging receipt or its `--json` result carries (files, their notices), app-relative. */
 export function reportedPaths(result) {
   const out = new Set();

package/stage-sidecar.mjs

@@ -603,17 +603,25 @@ export function defaultRun(command, args, { cwd, env = process.env } = {}) {
  */
 const isDebugSymbolMember = (member) => member.split("/").some((part) => part.toLowerCase().endsWith(".dsym"));
 
-export function defaultExtractMember({ archive, fileName, destDir, run = defaultRun }) {
+/**
+ * The tar that lists and unpacks archives. On Windows it is the System32 bsdtar, named explicitly: PATH often finds Git for Windows'
+ * GNU tar first, which reads the colon in `D:\...` as a remote host and cannot list the cached archive (as direct-bootstrap.mjs).
+ */
+export function archiveTar({ platform = process.platform, env = process.env } = {}) {
+  return platform === "win32" ? path.win32.join(env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe") : "tar";
+}
+
+export function defaultExtractMember({ archive, fileName, destDir, run = defaultRun, tar = archiveTar() }) {
   const wanted = normalizeArchiveMember(fileName);
   if (wanted.error) fail("STAGE_SIDECAR_EXTRACT_FAILED", `archive member ${JSON.stringify(fileName)} ${wanted.error}`);
-  const listing = run("tar", ["-tf", archive], { cwd: path.dirname(archive) });
+  const listing = run(tar, ["-tf", archive], { cwd: path.dirname(archive) });
   if (listing.status !== 0) fail("STAGE_SIDECAR_EXTRACT_FAILED", `cannot list ${archive}`);
   const lines = String(listing.stdout).split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
   const members = wanted.byPath
     ? lines.filter((line) => (line.startsWith("./") ? line.slice(2) : line) === wanted.value)
     : lines.filter((line) => path.posix.basename(line) === wanted.value && !isDebugSymbolMember(line));
   if (members.length !== 1) fail("STAGE_SIDECAR_EXTRACT_FAILED", `${archive} has ${members.length} members ${wanted.byPath ? "at the path" : "named"} ${wanted.value}, expected exactly one`);
-  const extracted = run("tar", ["-xf", archive, "-C", destDir, members[0]], { cwd: path.dirname(archive) });
+  const extracted = run(tar, ["-xf", archive, "-C", destDir, members[0]], { cwd: path.dirname(archive) });
   if (extracted.status !== 0) fail("STAGE_SIDECAR_EXTRACT_FAILED", `cannot extract ${members[0]} from ${archive}`);
   const out = path.join(destDir, ...members[0].split("/"));
   const inside = path.relative(path.resolve(destDir), path.resolve(out));
@@ -1990,6 +1998,12 @@ export async function stageSidecars({ appRoot, manifest, target, cacheRoot, deps
   };
   validateStageSidecarReceipt(receipt, { target: plan.target.triple });
   const receiptFile = path.resolve(appRoot, plan.receiptPath);
+  // A receipt that would differ only in `stagedAt` is kept as it is: staging the same target again with the same results (the gate staged it
+  // first in a split, rightkit-gate stageSidecarsOnce) leaves every byte unchanged, so the gate's stage ledger sees no change to its staged outputs.
+  const sameAs = (old) => { const { stagedAt: _a, ...a } = old; const { stagedAt: _b, ...b } = receipt; return JSON.stringify(a) === JSON.stringify(b); };
+  let previous = null;
+  try { previous = JSON.parse(fs.readFileSync(receiptFile, "utf8")); } catch { previous = null; }
+  if (previous && sameAs(previous)) return { receipt: previous, receiptPath: receiptFile, files: previous.files, externalBinNames: previous.files.filter((file) => file.externalBin).map((file) => file.name), unchanged: true };
   fs.mkdirSync(path.dirname(receiptFile), { recursive: true });
   fs.writeFileSync(receiptFile, `${JSON.stringify(receipt, null, 2)}\n`);
   return { receipt, receiptPath: receiptFile, files, externalBinNames: files.filter((file) => file.externalBin).map((file) => file.name) };

package/suite-signing.mjs

@@ -34,6 +34,7 @@ import { signMacosEntries } from "./mac-sign-core.mjs";
 import { runMacCodesignCommands } from "./macos-signing-session.mjs";
 import { resolveManagedRoots } from "./managed-roots.mjs";
 import { isInside, realish } from "./qa-snapshot.mjs";
+import { GATE_TARGET_DIRS_ENV } from "./qa-layout.mjs";
 import { requireSignerToken, signWindowsFiles, verifyWindowsFiles } from "./sign-windows.mjs";
 import { QA_APP_BINARY_ENV, QA_SIGNED_FILES_ENV, SIGN_SUBJECT, SIGN_TEAM, SuiteSigningError, assertBundleIdMatches, containedRelative, productIdentity } from "./suite-signing-policy.mjs";
 
@@ -52,6 +53,31 @@ function codesignReport(file, { run, env, root }) {
   return { identifier: /^Identifier=(.+)$/m.exec(text)?.[1]?.trim(), team: /^TeamIdentifier=(.+)$/m.exec(text)?.[1]?.trim(), adhoc: /^Signature=adhoc$/m.test(text) };
 }
 
+// The QA bundle runs under app.rightkit.qa.<id> with no embedded.provisionprofile, so a provisioning profile bound to the product id cannot apply to it, and
+// AMFI refuses to spawn a bundle that claims a profile-gated entitlement without one (POSIX 163, "Launchd job spawn failed"). Suite (QA) signing therefore
+// drops the profile-gated keys; profile-gated capabilities (iCloud/CloudKit, push) are not exercisable in Mac source QA. Release signing never goes through here.
+const isProfileGatedEntitlement = (key) => key === "com.apple.application-identifier" || key === "com.apple.developer.team-identifier" || key.startsWith("com.apple.developer.") || key === "aps-environment" || key === "keychain-access-groups";
+
+/** The entitlements file to sign `index` with: the original when no key is profile-gated, else a derived plist in signedDir without them. */
+function qaEntitlements({ file, index, signedDir, run, env, root }) {
+  const options = { cwd: root, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true, shell: false };
+  const failed = (why) => refuse("SIGN_ENTITLEMENTS_UNREADABLE", `cannot read the entitlements ${file}: ${why}`, { file });
+  const read = run("plutil", ["-convert", "json", "-o", "-", file], options);
+  if (read?.error || read?.status !== 0) failed(read?.error?.message || output(read).trim() || `plutil exit ${read?.status ?? "unavailable"}`);
+  let parsed;
+  try { parsed = JSON.parse(read.stdout); } catch (cause) { failed(`plutil did not return JSON (${cause.message})`); }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) failed("the plist is not a dictionary");
+  const dropped = Object.keys(parsed).filter(isProfileGatedEntitlement);
+  if (!dropped.length) return { file, dropped };
+  const derivedDir = path.join(signedDir, "qa-entitlements");
+  fs.mkdirSync(derivedDir, { recursive: true });
+  const derived = path.join(derivedDir, `${index}.plist`);
+  fs.writeFileSync(derived, JSON.stringify(Object.fromEntries(Object.entries(parsed).filter(([key]) => !isProfileGatedEntitlement(key)))));
+  const write = run("plutil", ["-convert", "xml1", derived], options);
+  if (write?.error || write?.status !== 0) failed(`cannot write ${derived}: ${write?.error?.message || output(write).trim() || `plutil exit ${write?.status ?? "unavailable"}`}`);
+  return { file: derived, dropped };
+}
+
 /** Mac: sign each copy and read it back against the release-shaped identity. Returns one evidence record per file. */
 function signMac({ copies, name, config, appRoot, env, run, deps, identifier, install, signedDir, mainIndex }) {
   const settings = readDevSigningSettings(install, config, { root: appRoot });
@@ -78,6 +104,13 @@ function signMac({ copies, name, config, appRoot, env, run, deps, identifier, in
     const entitlements = (index === mainIndex ? lookupBundlePath(settings.entitlements, ".") : undefined) ?? lookupBundlePath(settings.entitlements, relative);
     return { file: copy.file, ...(id !== undefined ? { identifier: id } : {}), expectedIdentifier: id ?? path.basename(copy.file), ...(entitlements ? { entitlements } : {}) };
   });
+  entries.forEach((entry, index) => {
+    entry.entitlementsDropped = [];
+    if (!entry.entitlements) return;
+    const derived = qaEntitlements({ file: entry.entitlements, index, signedDir, run, env, root: appRoot });
+    entry.entitlements = derived.file;
+    entry.entitlementsDropped = derived.dropped;
+  });
   const signOne = deps.signOne ?? ((args) => runMacCodesignCommands([args], { env, run, cwd: appRoot })[0]);
   const inspect = deps.inspect ?? ((command, args) => {
     const result = run(command, args, { cwd: appRoot, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true, shell: false });
@@ -85,7 +118,7 @@ function signMac({ copies, name, config, appRoot, env, run, deps, identifier, in
     return output(result);
   });
   let records;
-  try { records = signMacosEntries(entries.map(({ expectedIdentifier: _derived, ...entry }) => entry), { identity: signing.identity, signOne, inspect, bundle: signedDir }); }
+  try { records = signMacosEntries(entries.map(({ expectedIdentifier: _derived, entitlementsDropped: _dropped, ...entry }) => entry), { identity: signing.identity, signOne, inspect, bundle: signedDir }); }
   catch (cause) { refuse("SIGN_FAILED", `${name}: ${cause.message}`, { cause }); }
   return records.map((record, index) => {
     const entry = entries[index];
@@ -99,7 +132,7 @@ function signMac({ copies, name, config, appRoot, env, run, deps, identifier, in
     catch (error) { if (!(error instanceof MacosDevelopmentSigningError)) throw error; refuse("SIGN_REQUIREMENT_MISMATCH", `${copies[index].path}: ${error.message}`, { expected, actual: error.installedRequirement }); }
     // assertStableDesignatedRequirement is silent about an unreadable or cdhash-bound requirement (it has no grants to protect); here either is a refusal.
     if (requirement !== expected) refuse("SIGN_REQUIREMENT_MISMATCH", `${copies[index].path}: the designated requirement could not be read back, or is cdhash-bound, instead of ${JSON.stringify(expected)}`, { expected });
-    return { platform: "mac", file: copies[index].path, signed: record.file, sha256Before: record.before.sha256, sha256After: record.after.sha256, identifier: entry.expectedIdentifier, team: report.team, identity: signing.identity, requirement };
+    return { platform: "mac", file: copies[index].path, signed: record.file, sha256Before: record.before.sha256, sha256After: record.after.sha256, identifier: entry.expectedIdentifier, team: report.team, identity: signing.identity, requirement, entitlementsDropped: entry.entitlementsDropped };
   });
 }
 
@@ -164,7 +197,9 @@ export function runSignStep({ name, sign, appRoot, config, env = process.env, pl
     const { identifier, mainBinaryName } = productIdentity({ readFile: read, manifestPath: install.manifestPath });
     assertBundleIdMatches(config, identifier);
     // 2. Where each file comes from.
-    if (!carried?.map) refuse("SIGN_RECEIPT_MISSING", `${name}: no carried receipts in this environment (${carried?.error ?? "RIGHTKIT_CARRIED_CARGO_MAP is not set"}); a sign step signs a file named by an earlier suite's signed receipt`);
+    // A broker host names a suite's outputs by its carried receipts; a direct host by the output directories the gate pinned for the stage
+    // (RIGHTKIT_GATE_TARGET_DIRS, test-command.mjs). With neither, nothing says where a suite's files are, and nothing is signed.
+    if (!carried?.map && !env[GATE_TARGET_DIRS_ENV]) refuse("SIGN_RECEIPT_MISSING", `${name}: no carried receipts in this environment (${carried?.error ?? "RIGHTKIT_CARRIED_CARGO_MAP is not set"}) and no gate-pinned output directories (${GATE_TARGET_DIRS_ENV}); a sign step signs a file an earlier suite built`);
     if (typeof outputDirsOf !== "function") refuse("SIGN_RECEIPT_MISSING", `${name}: the run has no receipt reader`);
     const sources = sign.files.map((item, index) => {
       const file = { ...item, path: containedRelative(item.path, `${name}.files[${index}].path`) };
@@ -175,7 +210,8 @@ export function runSignStep({ name, sign, appRoot, config, env = process.env, pl
     // 3. A gate-managed copy, outside everything the build owns.
     const signingRoot = deps.signingDirectory ?? defaultSigningDirectory({ env, platform });
     signedDir = path.join(signingRoot, `${name}-${process.pid}-${Date.now().toString(36)}-${randomBytes(4).toString("hex")}`);
-    const section = carried.map.broker ?? {};
+    // A direct host (no carrier) has no broker section: the checkout and the suites' own output directories are still forbidden.
+    const section = carried?.map?.broker ?? {};
     const forbidden = [section.snapshot?.path, section.checkout, env.RK_GATE_CHECKOUT, ...sources.flatMap((source) => source.dirs)].filter((p) => typeof p === "string" && p);
     for (const place of forbidden) if (isInside(signedDir, place)) refuse("SIGN_COPY_PLACE", `${name}: the signing directory ${signedDir} is inside ${place} (the snapshot, the checkout or a broker output directory)`);
     fs.mkdirSync(signedDir, { recursive: true, mode: 0o700 });

package/swift-lock.mjs

@@ -0,0 +1,334 @@
+// File-only SwiftPM lockfile check (class A scan `swift-lock`; Adrian 2026-11-01: "the build should not be able to proceed if the lockfile
+// isn't a match"). Like `cargo --locked` and `pnpm --frozen-lockfile`, a committed Package.resolved that disagrees with the declared
+// dependencies must fail before any compile. This module reads committed files and executes nothing: Package.swift is code, so SwiftPM is
+// never run; the `.package(...)` declarations are read literally, and a declaration that cannot be read literally is a finding (never a
+// silent pass). It checks the ROOT package's own declarations against the pins: transitive pins and the pins' own consistency with
+// dependency manifests are SwiftPM's (`--disable-automatic-resolution` in the class B swift-build scan).
+import path from "node:path";
+
+// ---- versions -------------------------------------------------------------------------------------------------------------
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+export function parseVersion(text) {
+  const m = SEMVER.exec(String(text ?? "").trim());
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre: m[4] ? m[4].split(".") : [], text: String(text).trim() };
+}
+const cmpIdent = (a, b) => {
+  const an = /^\d+$/.test(a); const bn = /^\d+$/.test(b);
+  if (an && bn) return Math.sign(Number(a) - Number(b));
+  if (an) return -1;
+  if (bn) return 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+};
+export function compareVersions(a, b) {
+  for (const k of ["major", "minor", "patch"]) if (a[k] !== b[k]) return a[k] < b[k] ? -1 : 1;
+  if (!a.pre.length && !b.pre.length) return 0;
+  if (!a.pre.length) return 1;
+  if (!b.pre.length) return -1;
+  for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
+    if (a.pre[i] === undefined) return -1;
+    if (b.pre[i] === undefined) return 1;
+    const c = cmpIdent(a.pre[i], b.pre[i]);
+    if (c) return c;
+  }
+  return 0;
+}
+const V = (major, minor, patch) => ({ major, minor, patch, pre: [], text: `${major}.${minor}.${patch}` });
+
+/** Requirement as { type, ... } -> readable text. */
+export function requirementText(r) {
+  switch (r.type) {
+    case "exact": return `exact ${r.version}`;
+    case "from": case "upToNextMajor": return `from ${r.version} (up to next major)`;
+    case "upToNextMinor": return `from ${r.version} (up to next minor)`;
+    case "range": return `${r.lower}${r.closed ? "..." : "..<"}${r.upper}`;
+    case "branch": return `branch ${r.branch}`;
+    case "revision": return `revision ${r.revision}`;
+    default: return JSON.stringify(r);
+  }
+}
+
+/** null when the pin ({ version, branch, revision }) satisfies the requirement, else the reason. */
+export function requirementProblem(req, pin) {
+  const pinned = pin.version ? `version ${pin.version}` : pin.branch ? `branch ${pin.branch}` : pin.revision ? `revision ${pin.revision}` : "no version";
+  if (req.type === "branch") return pin.branch === req.branch ? null : `pins ${pinned}, not branch ${req.branch}`;
+  if (req.type === "revision") return pin.revision && String(pin.revision).toLowerCase() === req.revision.toLowerCase() ? null : `pins ${pinned}, not revision ${req.revision}`;
+  const v = parseVersion(pin.version);
+  if (!v) return `pins ${pinned}, which is not a semantic version`;
+  const lo = (text) => parseVersion(text);
+  switch (req.type) {
+    case "exact": { const want = lo(req.version); return compareVersions(v, want) === 0 ? null : `pins version ${pin.version}, not ${req.version}`; }
+    case "from": case "upToNextMajor": { const a = lo(req.version); return compareVersions(v, a) >= 0 && compareVersions(v, V(a.major + 1, 0, 0)) < 0 ? null : `pins version ${pin.version}, outside ${req.version} up to next major`; }
+    case "upToNextMinor": { const a = lo(req.version); return compareVersions(v, a) >= 0 && compareVersions(v, V(a.major, a.minor + 1, 0)) < 0 ? null : `pins version ${pin.version}, outside ${req.version} up to next minor`; }
+    case "range": {
+      const a = lo(req.lower); const b = lo(req.upper);
+      const upper = compareVersions(v, b);
+      return compareVersions(v, a) >= 0 && (req.closed ? upper <= 0 : upper < 0) ? null : `pins version ${pin.version}, outside ${req.lower}${req.closed ? "..." : "..<"}${req.upper}`;
+    }
+    default: return `has an unknown requirement kind ${req.type}`;
+  }
+}
+
+// ---- locations ------------------------------------------------------------------------------------------------------------
+/** SwiftPM's package identity of a URL or path: its last path component without `.git`, lower-cased. */
+export function identityOf(location) {
+  const parts = String(location).replace(/[\\/]+$/, "").split(/[\\/:]/);
+  return (parts[parts.length - 1] ?? "").replace(/\.git$/i, "").toLowerCase();
+}
+/** A comparable form of a repository location: no scheme, user, `.git`, trailing slash or case; scp form equals URL form. */
+export function normalizeLocation(location) {
+  let t = String(location).trim().toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, "").replace(/^[^@/]+@/, "");
+  t = t.replace(/^([^/:]+):(?!\d+\/)/, "$1/").replace(/\/+$/, "").replace(/\.git$/, "").replace(/\/+$/, "");
+  return t;
+}
+
+// ---- Package.swift --------------------------------------------------------------------------------------------------------
+/** The text with comments blanked (newlines kept, offsets unchanged); string literals are left whole. */
+function maskComments(text) {
+  let out = ""; let i = 0;
+  while (i < text.length) {
+    const c = text[i]; const two = text.slice(i, i + 2);
+    if (text.startsWith('"""', i)) { const end = text.indexOf('"""', i + 3); const stop = end < 0 ? text.length : end + 3; out += text.slice(i, stop); i = stop; continue; }
+    if (c === '"') { let j = i + 1; while (j < text.length && text[j] !== '"' && text[j] !== "\n") j += text[j] === "\\" ? 2 : 1; out += text.slice(i, j + 1); i = j + 1; continue; }
+    if (two === "//") { while (i < text.length && text[i] !== "\n") { out += " "; i++; } continue; }
+    if (two === "/*") {
+      let depth = 0;
+      while (i < text.length) {
+        if (text.startsWith("/*", i)) { depth++; out += "  "; i += 2; } else if (text.startsWith("*/", i)) { depth--; out += "  "; i += 2; if (!depth) break; } else { out += text[i] === "\n" ? "\n" : " "; i++; }
+      }
+      continue;
+    }
+    out += c; i++;
+  }
+  return out;
+}
+
+/** Index just past the `)` that closes the `(` at `open`, or -1. Strings are skipped whole. */
+function closeParen(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"') { if (text.startsWith('"""', i)) { const e = text.indexOf('"""', i + 3); if (e < 0) return -1; i = e + 2; continue; } i++; while (i < text.length && text[i] !== '"' && text[i] !== "\n") i += text[i] === "\\" ? 2 : 1; continue; }
+    if (c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ")" || c === "]" || c === "}") { depth--; if (depth === 0) return i + 1; if (depth < 0) return -1; }
+  }
+  return -1;
+}
+
+function splitArgs(body) {
+  const args = []; let depth = 0; let start = 0;
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (c === '"') { i++; while (i < body.length && body[i] !== '"') i += body[i] === "\\" ? 2 : 1; continue; }
+    if (c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ")" || c === "]" || c === "}") depth--;
+    else if (c === "," && depth === 0) { args.push(body.slice(start, i)); start = i + 1; }
+  }
+  const last = body.slice(start);
+  if (last.trim() !== "" || args.length) args.push(last);
+  return args.map((a) => a.trim());
+}
+
+const STR = '"((?:[^"\\\\\\n]|\\\\[^(\\n])*)"';
+const strOf = (expr) => { const m = new RegExp(`^${STR}$`).exec(expr.trim()); return m ? m[1] : null; };
+const RANGE = new RegExp(`^${STR}\\s*(\\.\\.<|\\.\\.\\.)\\s*${STR}$`);
+const FUNC = new RegExp(`^(?:Package\\.Dependency\\.Requirement)?\\.(upToNextMajor|upToNextMinor|exact|branch|revision)\\(\\s*(?:(?:from|_)\\s*:\\s*)?${STR}\\s*\\)$`);
+
+function versionOrNull(s) { return parseVersion(s) ? s : null; }
+
+/** Parse one `.package(...)` argument list: { kind: "remote"|"local", url, path, requirement } or { problem }. */
+function parseDependency(args) {
+  let url = null; let local = null; let requirement = null;
+  const fail = (problem) => ({ problem });
+  for (const arg of args) {
+    const lab = /^([A-Za-z_]\w*)\s*:\s*([\s\S]*)$/.exec(arg);
+    if (lab) {
+      const [, label, expr] = lab;
+      if (label === "name" || label === "traits") continue;
+      if (label === "url") { url = strOf(expr); if (url === null) return fail(`url is not a string literal (${arg.slice(0, 60)})`); continue; }
+      if (label === "path") { local = strOf(expr); if (local === null) return fail(`path is not a string literal (${arg.slice(0, 60)})`); continue; }
+      if (label === "exact" || label === "from") {
+        const v = strOf(expr);
+        if (v === null || !versionOrNull(v)) return fail(`${label}: is not a literal semantic version (${expr.slice(0, 60)})`);
+        if (requirement) return fail("more than one requirement");
+        requirement = label === "exact" ? { type: "exact", version: v } : { type: "from", version: v };
+        continue;
+      }
+      if (label === "branch" || label === "revision") {
+        const v = strOf(expr);
+        if (v === null || v === "") return fail(`${label}: is not a literal string (${expr.slice(0, 60)})`);
+        if (requirement) return fail("more than one requirement");
+        requirement = label === "branch" ? { type: "branch", branch: v } : { type: "revision", revision: v };
+        continue;
+      }
+      return fail(`unsupported argument label ${label}:`);
+    }
+    if (requirement) return fail("more than one requirement");
+    const range = RANGE.exec(arg);
+    if (range) {
+      if (!versionOrNull(range[1]) || !versionOrNull(range[3])) return fail(`range bounds are not literal semantic versions (${arg.slice(0, 60)})`);
+      requirement = { type: "range", lower: range[1], upper: range[3], closed: range[2] === "..." };
+      continue;
+    }
+    const fn = FUNC.exec(arg);
+    if (fn) {
+      const [, kind, v] = fn;
+      if ((kind === "exact" || kind === "upToNextMajor" || kind === "upToNextMinor") && !versionOrNull(v)) return fail(`${kind} is not a literal semantic version (${arg.slice(0, 60)})`);
+      requirement = kind === "branch" ? { type: "branch", branch: v } : kind === "revision" ? { type: "revision", revision: v } : { type: kind, version: v };
+      continue;
+    }
+    return fail(`requirement is not a literal the checker reads (${arg.slice(0, 60)})`);
+  }
+  if (local !== null && url !== null) return fail("declares both url: and path:");
+  if (local !== null) return { kind: "local", path: local };
+  if (url === null) return fail("has no url: or path: (registry or computed dependency)");
+  if (!requirement) return fail("remote dependency has no requirement");
+  return { kind: "remote", url, requirement };
+}
+
+/** { deps: [{ line, kind, url, path, identity, requirement }], problems: [{ line, text }] } from Package.swift source, read literally. */
+export function parsePackageSwift(source) {
+  const text = maskComments(String(source));
+  const deps = []; const problems = [];
+  const lineAt = (idx) => text.slice(0, idx).split("\n").length;
+  // Lines inside an `#if` ... `#endif` region cannot be evaluated without Swift's compiler conditions.
+  const conditional = new Set(); let depth = 0;
+  text.split("\n").forEach((l, i) => {
+    const t = l.trim();
+    if (/^#if\b/.test(t)) depth++;
+    if (depth > 0) conditional.add(i + 1);
+    if (/^#endif\b/.test(t)) depth = Math.max(0, depth - 1);
+  });
+  const re = /\.package\s*\(/g; let m;
+  while ((m = re.exec(text))) {
+    const open = m.index + m[0].length - 1;
+    const line = lineAt(m.index);
+    const end = closeParen(text, open);
+    if (end < 0) { problems.push({ line, text: "unbalanced .package( declaration" }); break; }
+    const parsed = parseDependency(splitArgs(text.slice(open + 1, end - 1)));
+    re.lastIndex = end;
+    if (parsed.problem) { problems.push({ line, text: `.package declaration cannot be read literally: ${parsed.problem}` }); continue; }
+    if (conditional.has(line)) { problems.push({ line, text: `.package declaration is inside an #if region, which cannot be evaluated literally (${parsed.kind === "remote" ? parsed.url : parsed.path})` }); continue; }
+    deps.push({ line, ...parsed, identity: identityOf(parsed.kind === "remote" ? parsed.url : parsed.path) });
+  }
+  return { deps, problems };
+}
+
+// ---- Package.resolved -----------------------------------------------------------------------------------------------------
+/** { pins: [{ identity, location, version, branch, revision }], problems: [text] } for Package.resolved versions 1, 2 and 3. */
+export function parseResolved(source) {
+  let doc;
+  try { doc = JSON.parse(String(source).replace(/^/, "")); } catch (e) { return { pins: [], problems: [`not valid JSON: ${e.message}`] }; }
+  const v = doc?.version;
+  let raw;
+  if (v === 1) raw = doc?.object?.pins;
+  else if (v === 2 || v === 3) raw = doc?.pins;
+  else return { pins: [], problems: [`unsupported Package.resolved version ${JSON.stringify(v)} (the checker reads 1, 2 and 3)`] };
+  if (!Array.isArray(raw)) return { pins: [], problems: [`Package.resolved version ${v} has no pins array`] };
+  const pins = [];
+  for (const p of raw) {
+    const location = v === 1 ? p?.repositoryURL : p?.location;
+    if (typeof location !== "string") return { pins: [], problems: [`a Package.resolved version ${v} pin has no ${v === 1 ? "repositoryURL" : "location"}`] };
+    const state = p.state ?? {};
+    pins.push({ identity: identityOf(location), location, version: state.version ?? null, branch: state.branch ?? null, revision: state.revision ?? null });
+  }
+  return { pins, problems: [] };
+}
+
+/** Findings for the declared remote dependencies against the pins. `label(dep)` prefixes each finding with its file (and line). */
+function matchPins(deps, pins, { label, resolvedFile }) {
+  const out = [];
+  for (const d of deps) {
+    const named = pins.filter((p) => p.identity === d.identity);
+    const where = `${label(d)}: package ${d.identity} requires ${requirementText(d.requirement)}`;
+    if (!named.length) { out.push(`${where} but ${resolvedFile} has no pin for it`); continue; }
+    const pin = named.find((p) => normalizeLocation(p.location) === normalizeLocation(d.url));
+    if (!pin) { out.push(`${where} from ${d.url} but ${resolvedFile} pins ${named.map((p) => p.location).join(", ")}`); continue; }
+    const why = requirementProblem(d.requirement, pin);
+    if (why) out.push(`${where} but ${resolvedFile} ${why}`);
+  }
+  return out;
+}
+
+const join = (dir, f) => (dir === "" || dir === "." ? f : `${dir}/${f}`);
+const tryRead = (read, exists, file) => (exists(file) ? { text: read(file) } : null);
+
+/** Findings for the Swift package at `dir` (repo-relative, "." for the root). `read`/`exists` take repo-relative paths. */
+export function packageLockProblems({ dir, read, exists }) {
+  const manifest = join(dir, "Package.swift"); const resolvedFile = join(dir, "Package.resolved");
+  const src = tryRead(read, exists, manifest);
+  if (!src) return [];
+  const { deps, problems } = parsePackageSwift(src.text);
+  const out = problems.map((p) => `${manifest}:${p.line}: ${p.text}`);
+  const remote = deps.filter((d) => d.kind === "remote");
+  const resolved = tryRead(read, exists, resolvedFile);
+  if (!resolved) {
+    if (remote.length) out.push(`${manifest}: ${remote.length} remote ${remote.length === 1 ? "dependency" : "dependencies"} (${remote.map((d) => d.identity).join(", ")}) and no ${resolvedFile}; commit the lockfile`);
+    return out;
+  }
+  const parsed = parseResolved(resolved.text);
+  if (parsed.problems.length) return [...out, ...parsed.problems.map((p) => `${resolvedFile}: ${p}`)];
+  out.push(...matchPins(remote, parsed.pins, { label: (d) => `${manifest}:${d.line}`, resolvedFile }));
+  return out;
+}
+
+// ---- Xcode projects -------------------------------------------------------------------------------------------------------
+const unquote = (v) => { const t = v.trim(); return t.startsWith('"') && t.endsWith('"') ? t.slice(1, -1).replace(/\\"/g, '"') : t; };
+const field = (block, name) => { const m = new RegExp(`(?:^|[\\s;{])${name}\\s*=\\s*("(?:[^"\\\\]|\\\\.)*"|[^;\\s]+)\\s*;`).exec(block); return m ? unquote(m[1]) : null; };
+
+/** { deps, problems } for the XCRemoteSwiftPackageReference objects of a project.pbxproj. */
+export function parsePbxproj(source) {
+  const text = String(source); const deps = []; const problems = [];
+  const re = /isa\s*=\s*XCRemoteSwiftPackageReference\s*;/g; let m;
+  while ((m = re.exec(text))) {
+    const line = text.slice(0, m.index).split("\n").length;
+    const open = text.lastIndexOf("{", m.index);
+    let depth = 0; let end = -1;
+    for (let i = open; i < text.length; i++) { if (text[i] === "{") depth++; else if (text[i] === "}") { depth--; if (depth === 0) { end = i; break; } } }
+    if (open < 0 || end < 0) { problems.push({ line, text: "unbalanced XCRemoteSwiftPackageReference object" }); continue; }
+    const block = text.slice(open + 1, end);
+    const url = field(block, "repositoryURL");
+    const reqOpen = block.search(/requirement\s*=\s*\{/);
+    if (!url || reqOpen < 0) { problems.push({ line, text: "XCRemoteSwiftPackageReference has no repositoryURL or requirement the checker reads" }); continue; }
+    const req = block.slice(block.indexOf("{", reqOpen) + 1, block.indexOf("}", reqOpen));
+    const kind = field(req, "kind");
+    let requirement = null;
+    if (kind === "exactVersion") { const v = field(req, "version"); if (v && parseVersion(v)) requirement = { type: "exact", version: v }; }
+    else if (kind === "upToNextMajorVersion") { const v = field(req, "minimumVersion"); if (v && parseVersion(v)) requirement = { type: "upToNextMajor", version: v }; }
+    else if (kind === "upToNextMinorVersion") { const v = field(req, "minimumVersion"); if (v && parseVersion(v)) requirement = { type: "upToNextMinor", version: v }; }
+    else if (kind === "versionRange") { const a = field(req, "minimumVersion"); const b = field(req, "maximumVersion"); if (a && b && parseVersion(a) && parseVersion(b)) requirement = { type: "range", lower: a, upper: b, closed: false }; }
+    else if (kind === "branch") { const b = field(req, "branch"); if (b) requirement = { type: "branch", branch: b }; }
+    else if (kind === "revision") { const r = field(req, "revision"); if (r) requirement = { type: "revision", revision: r }; }
+    if (!requirement) { problems.push({ line, text: `requirement of ${url} cannot be read literally (kind ${kind ?? "missing"})` }); continue; }
+    deps.push({ line, kind: "remote", url, identity: identityOf(url), requirement });
+  }
+  return { deps, problems };
+}
+
+/** Findings for one `<name>.xcodeproj` directory (repo-relative). */
+export function xcodeProjectLockProblems({ project, read, exists }) {
+  const pbx = `${project}/project.pbxproj`;
+  const resolvedFile = `${project}/project.xcworkspace/xcshareddata/swiftpm/Package.resolved`;
+  const src = tryRead(read, exists, pbx);
+  if (!src) return [];
+  const { deps, problems } = parsePbxproj(src.text);
+  const out = problems.map((p) => `${pbx}:${p.line}: ${p.text}`);
+  const resolved = tryRead(read, exists, resolvedFile);
+  if (!resolved) {
+    if (deps.length) out.push(`${pbx}: ${deps.length} remote Swift ${deps.length === 1 ? "package" : "packages"} (${deps.map((d) => d.identity).join(", ")}) and no ${resolvedFile}; commit the lockfile`);
+    return out;
+  }
+  const parsed = parseResolved(resolved.text);
+  if (parsed.problems.length) return [...out, ...parsed.problems.map((p) => `${resolvedFile}: ${p}`)];
+  out.push(...matchPins(deps, parsed.pins, { label: (d) => `${pbx}:${d.line}`, resolvedFile }));
+  return out;
+}
+
+/** The scan's repository-relative lock owners for a changed file: a Swift package directory or an `.xcodeproj` directory. */
+export function lockOwnerOf(file, { exists, ancestorDirs }) {
+  const parts = file.split("/");
+  const xi = parts.findIndex((p) => p.endsWith(".xcodeproj"));
+  if (xi >= 0) return { kind: "xcode", dir: parts.slice(0, xi + 1).join("/") };
+  const owner = ancestorDirs(path.posix.dirname(file)).reverse().find((d) => exists(join(d, "Package.swift")));
+  return owner === undefined ? null : { kind: "package", dir: owner === "" ? "." : owner };
+}