vouchington-tooling 0.0.16 → 0.0.17

package/README.md

@@ -33,6 +33,14 @@ vouchington make-shard-matrix 4
 vouchington load-runner-env
 vouchington clean-workspace
 vouchington install-github-release --repo lycheeverse/lychee --version 0.24.2 --asset 'lychee-{platform}.tar.gz' --bin lychee
+vouchington run-with-timeout 120 10 docker push example
+vouchington lint-links --offline
+vouchington materialize-pr-context
+vouchington wait-for-apt-locks
+vouchington install-playwright-chromium-arm64
+vouchington ghcr-package-retention example%2Fapi
+vouchington nuget-central-version trusted.props candidate.props metadata.json out.props
+vouchington swift-semantic-equal BASE HEAD App.swift
 ```
 
 Host-lock environment:
@@ -92,6 +100,10 @@ import { runCiLocal } from 'vouchington-tooling/ci-local'
 import { rateLimitDelay } from 'vouchington-tooling/gha-rate-limit'
 import { parseCheckpoint } from 'vouchington-tooling/gha-pr-checkpoint'
 import { checkWorkspaceGatesPolicy } from 'vouchington-tooling/workspace-gates'
+import { validateNugetUpdate } from 'vouchington-tooling/nuget-central-version'
+import { normalizeSwiftSource } from 'vouchington-tooling/swift-semantic-equal'
+import { parseUniqueSwiftBinaryTargetChecksum } from 'vouchington-tooling/swift-source-offset'
+import { validateResolvedPinDelta } from 'vouchington-tooling/swift-resolved-pin-delta'
 ```
 
 The artifact, review-payload, HTTP body, and pagination APIs validate untrusted inputs at their

package/dist/cli/commands/nuget-central-version.d.mts

@@ -0,0 +1 @@
+export declare function runNugetCentralVersionCommand(args: readonly string[]): number;

package/dist/cli/commands/nuget-central-version.mjs

@@ -0,0 +1,11 @@
+import { runNugetCentralVersionCli } from '../../nuget-central-version/cli.mjs';
+export function runNugetCentralVersionCommand(args) {
+    try {
+        runNugetCentralVersionCli(args);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/cli/commands/swift-semantic-equal.d.mts

@@ -0,0 +1 @@
+export declare function runSwiftSemanticEqualCommand(args: readonly string[]): number;

package/dist/cli/commands/swift-semantic-equal.mjs

@@ -0,0 +1,4 @@
+import { runSwiftSemanticEqualCli } from '../../swift-semantic-equal/cli.mjs';
+export function runSwiftSemanticEqualCommand(args) {
+    return runSwiftSemanticEqualCli(args);
+}

package/dist/cli/index.mjs

@@ -9,6 +9,8 @@ import { runHttpOrigin } from './commands/http-origin.mjs';
 import { runPnpmInstallCli } from './commands/pnpm-install.mjs';
 import { runRunnerPortPolicy } from './commands/runner-port-policy.mjs';
 import { runScript } from './commands/spawn-script.mjs';
+import { runNugetCentralVersionCommand } from './commands/nuget-central-version.mjs';
+import { runSwiftSemanticEqualCommand } from './commands/swift-semantic-equal.mjs';
 import { runVitestBlobManifestCommand } from './commands/vitest-blob-manifest.mjs';
 import { runWithHostLock } from './commands/with-host-lock.mjs';
 import { parseCli } from './parse.mjs';
@@ -39,6 +41,15 @@ const SCRIPT_PATHS = {
     'load-runner-env': { command: 'bash', path: 'scripts/gha/load-runner-env.sh' },
     'clean-workspace': { command: 'bash', path: 'scripts/gha/clean-workspace.sh' },
     'install-github-release': { command: 'bash', path: 'scripts/gha/install-github-release.sh' },
+    'run-with-timeout': { command: 'bash', path: 'scripts/gha/run-with-timeout.sh' },
+    'lint-links': { command: 'bash', path: 'scripts/gha/lint-links.sh' },
+    'materialize-pr-context': { command: 'bash', path: 'scripts/gha/materialize-pr-context.sh' },
+    'wait-for-apt-locks': { command: 'bash', path: 'scripts/gha/wait-for-apt-locks.sh' },
+    'install-playwright-chromium-arm64': {
+        command: 'bash',
+        path: 'scripts/gha/install-playwright-chromium-arm64.sh',
+    },
+    'ghcr-package-retention': { command: 'bash', path: 'scripts/gha/ghcr-package-retention.sh' },
 };
 export function runCli(argv = process.argv) {
     const parsed = parseCli(argv);
@@ -67,6 +78,10 @@ export function runCli(argv = process.argv) {
             return runPnpmInstallCli(parsed.args);
         case 'vitest-blob-manifest':
             return runVitestBlobManifestCommand(parsed.args);
+        case 'nuget-central-version':
+            return runNugetCentralVersionCommand(parsed.args);
+        case 'swift-semantic-equal':
+            return runSwiftSemanticEqualCommand(parsed.args);
         case 'http-origin':
             return runHttpOrigin(parsed.field, parsed.value);
         case 'gha-artifacts-cleanup':

package/dist/cli/parse.d.mts

@@ -24,10 +24,16 @@ export type ParsedCli = {
 } | {
     kind: 'vitest-blob-manifest';
     args: string[];
+} | {
+    kind: 'nuget-central-version';
+    args: string[];
+} | {
+    kind: 'swift-semantic-equal';
+    args: string[];
 } | {
     kind: 'http-origin';
     field: string;
     value: string;
 } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup;
-export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release';
+export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'materialize-pr-context' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention';
 export declare function parseCli(argv: readonly string[]): ParsedCli;

package/dist/cli/parse.mjs

@@ -13,6 +13,12 @@ const SCRIPT_COMMANDS = new Set([
     'load-runner-env',
     'clean-workspace',
     'install-github-release',
+    'run-with-timeout',
+    'lint-links',
+    'materialize-pr-context',
+    'wait-for-apt-locks',
+    'install-playwright-chromium-arm64',
+    'ghcr-package-retention',
 ]);
 export function parseCli(argv) {
     const args = argv.slice(2);
@@ -31,6 +37,10 @@ export function parseCli(argv) {
         return { kind: 'pnpm-install', args: rest };
     if (command === 'vitest-blob-manifest')
         return { kind: 'vitest-blob-manifest', args: rest };
+    if (command === 'nuget-central-version')
+        return { kind: 'nuget-central-version', args: rest };
+    if (command === 'swift-semantic-equal')
+        return { kind: 'swift-semantic-equal', args: rest };
     if (command === 'http-origin')
         return parseHttpOrigin(rest);
     if (command === 'gha-artifacts-cleanup')

package/dist/cli/usage.d.mts

@@ -1,2 +1,2 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -20,6 +20,14 @@ Commands:
   load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards
   clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate
   install-github-release        Download a checksum-verified GitHub Release binary
+  run-with-timeout              Run a command with GNU timeout or a Perl fallback
+  lint-links                    Two-pass lychee: internal links fail, external warn
+  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl
+  wait-for-apt-locks            Wait until apt/dpkg lock files are free
+  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json
+  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN
+  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta
+  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace
 
 Options:
   -h, --help       Show this help
@@ -61,7 +69,15 @@ check-cache-size <path> <max-bytes> <label>
 make-shard-matrix <total>
 load-runner-env
 clean-workspace
-install-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name
+install-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]
+run-with-timeout <timeout-seconds> <kill-after-seconds> <command...>
+lint-links [--offline] [--config PATH] [--glob PATTERN] [files...]
+materialize-pr-context
+wait-for-apt-locks
+install-playwright-chromium-arm64 [name:archive...]
+ghcr-package-retention <url-encoded-package>...
+nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>
+swift-semantic-equal <base> <head> <file.swift>
 `;
 export function printUsage(stream = process.stdout) {
     stream.write(USAGE);

package/dist/index.d.mts

@@ -49,3 +49,8 @@ export { CHECKPOINT_MARKER, isTrustedCheckpointComment, parseCheckpoint, renderC
 export type { Checkpoint, CheckpointCodecOptions, GitHubComment, } from './gha-pr-checkpoint/index.mts';
 export { checkWorkspaceGatesPolicy } from './workspace-gates/index.mts';
 export type { WorkspaceGatesOptions } from './workspace-gates/index.mts';
+export { validateNugetUpdate } from './nuget-central-version/index.mts';
+export { normalizeSwiftSource } from './swift-semantic-equal/index.mts';
+export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from './swift-source-offset/index.mts';
+export { validateResolvedPinDelta } from './swift-resolved-pin-delta/index.mts';
+export type { ResolvedDocument, ResolvedPin, ValidateResolvedPinDeltaOptions, } from './swift-resolved-pin-delta/index.mts';

package/dist/index.mjs

@@ -28,3 +28,7 @@ export { assertWorkflowCommandDrift, parseCiLocalArgs, runCiLocal } from './ci-l
 export { GitHubRateLimitError, isRateLimited, isRetryableCancellationError, MAX_RATE_LIMIT_WAIT_MS, rateLimitDelay, reserveRateLimitDelay, } from './gha-rate-limit/index.mjs';
 export { CHECKPOINT_MARKER, isTrustedCheckpointComment, parseCheckpoint, renderCheckpoint, sortedCheckpointCandidates, validateCheckpoint, } from './gha-pr-checkpoint/index.mjs';
 export { checkWorkspaceGatesPolicy } from './workspace-gates/index.mjs';
+export { validateNugetUpdate } from './nuget-central-version/index.mjs';
+export { normalizeSwiftSource } from './swift-semantic-equal/index.mjs';
+export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from './swift-source-offset/index.mjs';
+export { validateResolvedPinDelta } from './swift-resolved-pin-delta/index.mjs';

package/dist/nuget-central-version/cli.d.mts

@@ -0,0 +1 @@
+export declare function runNugetCentralVersionCli(args: readonly string[]): void;

package/dist/nuget-central-version/cli.mjs

@@ -0,0 +1,11 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { validateNugetUpdate } from './index.mjs';
+export function runNugetCentralVersionCli(args) {
+    const [trustedPath, candidatePath, metadataPath, outputPath] = args;
+    if (!trustedPath || !candidatePath || !metadataPath || !outputPath || args.length !== 4) {
+        throw new Error('Usage: vouchington nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>');
+    }
+    const candidateSource = readFileSync(candidatePath, 'utf8');
+    validateNugetUpdate(readFileSync(trustedPath, 'utf8'), candidateSource, readFileSync(metadataPath, 'utf8'));
+    writeFileSync(outputPath, candidateSource);
+}

package/dist/nuget-central-version/index.d.mts

@@ -0,0 +1 @@
+export declare function validateNugetUpdate(trustedSource: string, candidateSource: string, metadataSource: string): string[];

package/dist/nuget-central-version/index.mjs

@@ -0,0 +1,74 @@
+const packageVersionPattern = /<PackageVersion\s+Include="(?<name>[^"]+)"\s+Version="(?<version>[^"]+)"\s*\/>/g;
+const literalNugetVersionPattern = /^\d+(?:\.\d+){1,3}(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?(?:\+[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/;
+function parseVersions(source) {
+    const versions = new Map();
+    for (const match of source.matchAll(packageVersionPattern)) {
+        const name = match.groups?.name;
+        const version = match.groups?.version;
+        if (!name || !version || versions.has(name)) {
+            throw new Error('Directory.Packages.props must contain unique PackageVersion entries');
+        }
+        versions.set(name, { literal: match[0], version });
+    }
+    if (versions.size === 0)
+        throw new Error('Directory.Packages.props has no PackageVersion entries');
+    return versions;
+}
+export function validateNugetUpdate(trustedSource, candidateSource, metadataSource) {
+    const trusted = parseVersions(trustedSource);
+    const candidate = parseVersions(candidateSource);
+    if (candidate.size !== trusted.size) {
+        throw new Error('Dependabot may not add or remove central package declarations');
+    }
+    const changed = [];
+    let expected = trustedSource;
+    for (const [name, trustedEntry] of trusted) {
+        const candidateEntry = candidate.get(name);
+        if (!candidateEntry)
+            throw new Error(`Dependabot removed central package ${name}`);
+        if (candidateEntry.version === trustedEntry.version)
+            continue;
+        if (!literalNugetVersionPattern.test(trustedEntry.version)) {
+            throw new Error(`Dependabot may not change MSBuild-managed version for ${name}`);
+        }
+        if (!literalNugetVersionPattern.test(candidateEntry.version)) {
+            throw new Error(`Dependabot proposed a non-literal NuGet version for ${name}`);
+        }
+        changed.push(name);
+        expected = expected.replace(trustedEntry.literal, trustedEntry.literal.replace(`Version="${trustedEntry.version}"`, `Version="${candidateEntry.version}"`));
+    }
+    if (changed.length === 0)
+        throw new Error('Dependabot NuGet update changed no package versions');
+    if (candidateSource !== expected) {
+        throw new Error('Dependabot may change only literal central PackageVersion values');
+    }
+    const metadata = JSON.parse(metadataSource);
+    if (!Array.isArray(metadata))
+        throw new Error('Dependabot NuGet metadata must be an array');
+    const metadataByName = new Map();
+    for (const update of metadata) {
+        const name = update.dependencyName?.toLowerCase();
+        if (!name || !update.prevVersion || !update.newVersion || metadataByName.has(name)) {
+            throw new Error('Dependabot NuGet metadata must identify every changed package exactly once');
+        }
+        metadataByName.set(name, update);
+    }
+    const metadataNames = [...metadataByName.keys()].toSorted();
+    const changedNames = changed.map((name) => name.toLowerCase()).toSorted();
+    if (metadataNames.length !== changedNames.length ||
+        new Set(metadataNames).size !== metadataNames.length) {
+        throw new Error('Dependabot NuGet metadata must identify every changed package exactly once');
+    }
+    if (!metadataNames.every((name, index) => name === changedNames[index])) {
+        throw new Error('Dependabot NuGet metadata does not match the changed central packages');
+    }
+    for (const name of changed) {
+        const update = metadataByName.get(name.toLowerCase());
+        const trustedVersion = trusted.get(name)?.version;
+        const candidateVersion = candidate.get(name)?.version;
+        if (update?.prevVersion !== trustedVersion || update?.newVersion !== candidateVersion) {
+            throw new Error(`Dependabot NuGet metadata versions do not match ${name}`);
+        }
+    }
+    return changed.toSorted();
+}

package/dist/swift-resolved-pin-delta/index.d.mts

@@ -0,0 +1,18 @@
+export type ResolvedPin = {
+    identity?: string;
+    kind?: string;
+    location?: string;
+    state?: {
+        revision?: string;
+        version?: string;
+    };
+};
+export type ResolvedDocument = {
+    originHash?: string;
+    pins?: ResolvedPin[];
+    version?: number;
+};
+export type ValidateResolvedPinDeltaOptions = {
+    requiredIdentity?: string;
+};
+export declare function validateResolvedPinDelta(trustedResolved: ResolvedDocument, candidateResolved: ResolvedDocument, options?: ValidateResolvedPinDeltaOptions): void;

package/dist/swift-resolved-pin-delta/index.mjs

@@ -0,0 +1,63 @@
+function isExactSemver(value) {
+    const match = value?.match(/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?<prerelease>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/);
+    return Boolean(match &&
+        !match.groups?.prerelease
+            ?.split('.')
+            .some((identifier) => /^\d+$/.test(identifier) && identifier.length > 1 && identifier[0] === '0'));
+}
+function exactPins(resolved) {
+    if (!Array.isArray(resolved.pins))
+        throw new Error('Package.resolved must contain pins');
+    const pins = new Map();
+    for (const pin of resolved.pins) {
+        const state = pin.state;
+        if (!pin.identity?.match(/^[a-z0-9][a-z0-9.-]*$/) ||
+            pin.kind !== 'remoteSourceControl' ||
+            !pin.location?.match(/^https:\/\/[^\s]+$/) ||
+            !state?.revision?.match(/^[a-f0-9]{40}$/) ||
+            !isExactSemver(state.version) ||
+            Object.keys(pin).toSorted().join(',') !== 'identity,kind,location,state' ||
+            Object.keys(state).toSorted().join(',') !== 'revision,version') {
+            throw new Error('Package.resolved pins must remain fully specified exact pins');
+        }
+        if (pins.has(pin.identity)) {
+            throw new Error('Package.resolved must contain unique pin identities');
+        }
+        pins.set(pin.identity, pin);
+    }
+    return pins;
+}
+function canonicalPin(pin) {
+    return JSON.stringify({
+        identity: pin.identity,
+        kind: pin.kind,
+        location: pin.location,
+        state: { revision: pin.state.revision, version: pin.state.version },
+    });
+}
+export function validateResolvedPinDelta(trustedResolved, candidateResolved, options = {}) {
+    const requiredIdentity = options.requiredIdentity ?? 'skip';
+    if (trustedResolved.version !== 3 ||
+        candidateResolved.version !== 3 ||
+        !candidateResolved.originHash?.match(/^[a-f0-9]{64}$/)) {
+        throw new Error('Package.resolved must remain a version 3 lock with an origin hash');
+    }
+    const trustedPins = exactPins(trustedResolved);
+    const candidatePins = exactPins(candidateResolved);
+    const trustedRequired = trustedPins.get(requiredIdentity);
+    const candidateRequired = candidatePins.get(requiredIdentity);
+    if (!trustedRequired ||
+        !candidateRequired ||
+        trustedRequired.kind !== candidateRequired.kind ||
+        trustedRequired.location !== candidateRequired.location) {
+        throw new Error(`Package.resolved must keep the trusted ${requiredIdentity} source`);
+    }
+    for (const [identity, trustedPin] of trustedPins) {
+        if (identity === requiredIdentity)
+            continue;
+        const candidatePin = candidatePins.get(identity);
+        if (!candidatePin || canonicalPin(candidatePin) !== canonicalPin(trustedPin)) {
+            throw new Error(`Package.resolved must keep every trusted non-${requiredIdentity} pin unchanged`);
+        }
+    }
+}

package/dist/swift-semantic-equal/cli.d.mts

@@ -0,0 +1,2 @@
+import { execFileSync } from 'node:child_process';
+export declare function runSwiftSemanticEqualCli(args: readonly string[], gitShow?: typeof execFileSync): number;

package/dist/swift-semantic-equal/cli.mjs

@@ -0,0 +1,26 @@
+import { execFileSync } from 'node:child_process';
+import { normalizeSwiftSource } from './normalize.mjs';
+export function runSwiftSemanticEqualCli(args, gitShow = execFileSync) {
+    const [base, head, file] = args;
+    if (!base || !head || !file || args.length !== 3 || !file.endsWith('.swift')) {
+        return 1;
+    }
+    try {
+        const baseSource = gitShow('git', ['show', `${base}:${file}`], {
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const headSource = gitShow('git', ['show', `${head}:${file}`], {
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return normalizeSwiftSource(String(baseSource)) === normalizeSwiftSource(String(headSource))
+            ? 0
+            : 1;
+    }
+    catch {
+        return 1;
+    }
+}

package/dist/swift-semantic-equal/index.d.mts

@@ -0,0 +1 @@
+export { normalizeSwiftSource } from './normalize.mts';

package/dist/swift-semantic-equal/index.mjs

@@ -0,0 +1 @@
+export { normalizeSwiftSource } from './normalize.mjs';

package/dist/swift-semantic-equal/normalize.d.mts

@@ -0,0 +1 @@
+export declare function normalizeSwiftSource(source: string): string;

package/dist/swift-semantic-equal/normalize.mjs

@@ -0,0 +1,108 @@
+export function normalizeSwiftSource(source) {
+    let normalized = '';
+    let index = 0;
+    while (index < source.length) {
+        const char = source[index];
+        if (char === undefined || /\s/u.test(char)) {
+            index += 1;
+            continue;
+        }
+        if (source.startsWith('//', index)) {
+            index = skipLineComment(source, index);
+            continue;
+        }
+        if (source.startsWith('/*', index)) {
+            index = skipBlockComment(source, index);
+            continue;
+        }
+        const hashCount = countLeadingHashes(source, index);
+        const afterHashes = source[index + hashCount];
+        if (afterHashes === '"') {
+            const literal = readSwiftStringLiteral(source, index, hashCount);
+            if (literal) {
+                normalized += literal.text;
+                index = literal.end;
+                continue;
+            }
+        }
+        if (afterHashes === '/') {
+            const literal = readSwiftRegexLiteral(source, index, hashCount, normalized);
+            if (literal) {
+                normalized += literal.text;
+                index = literal.end;
+                continue;
+            }
+        }
+        normalized += char;
+        index += 1;
+    }
+    return normalized;
+}
+function countLeadingHashes(source, start) {
+    let count = 0;
+    while (source[start + count] === '#')
+        count += 1;
+    return count;
+}
+function skipLineComment(source, start) {
+    const end = source.indexOf('\n', start + 2);
+    return end === -1 ? source.length : end + 1;
+}
+function skipBlockComment(source, start) {
+    let depth = 1;
+    let index = start + 2;
+    while (index < source.length && depth > 0) {
+        if (source.startsWith('/*', index)) {
+            depth += 1;
+            index += 2;
+        }
+        else if (source.startsWith('*/', index)) {
+            depth -= 1;
+            index += 2;
+        }
+        else {
+            index += 1;
+        }
+    }
+    return index;
+}
+function readSwiftStringLiteral(source, start, hashCount) {
+    const openingQuote = start + hashCount;
+    const isTripleQuoted = source.startsWith('"""', openingQuote);
+    const openerLength = hashCount + (isTripleQuoted ? 3 : 1);
+    const closer = `${isTripleQuoted ? '"""' : '"'}${'#'.repeat(hashCount)}`;
+    let index = start + openerLength;
+    while (index < source.length) {
+        if (!isTripleQuoted && hashCount === 0 && source[index] === '\\') {
+            index += 2;
+            continue;
+        }
+        if (source.startsWith(closer, index)) {
+            return { end: index + closer.length, text: source.slice(start, index + closer.length) };
+        }
+        index += 1;
+    }
+    return null;
+}
+function readSwiftRegexLiteral(source, start, hashCount, normalizedPrefix) {
+    if (hashCount === 0 && !canStartBareRegex(normalizedPrefix))
+        return null;
+    const closer = `/${'#'.repeat(hashCount)}`;
+    let index = start + hashCount + 1;
+    while (index < source.length) {
+        if (hashCount === 0 && source[index] === '\\') {
+            index += 2;
+            continue;
+        }
+        if (source.startsWith(closer, index)) {
+            return { end: index + closer.length, text: source.slice(start, index + closer.length) };
+        }
+        index += 1;
+    }
+    return null;
+}
+function canStartBareRegex(normalizedPrefix) {
+    if (normalizedPrefix.length === 0)
+        return true;
+    return /[({[=,:;!&|?]/u.test(normalizedPrefix.at(-1));
+}

package/dist/swift-source-offset/index.d.mts

@@ -0,0 +1,2 @@
+export declare function isSwiftCodeOffset(source: string, offset: number): boolean;
+export declare function parseUniqueSwiftBinaryTargetChecksum(source: string, targetName: string, expectedUrl: string): string | undefined;

package/dist/swift-source-offset/index.mjs

@@ -0,0 +1,68 @@
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function isSwiftCodeOffset(source, offset) {
+    let blockCommentDepth = 0;
+    let escaped = false;
+    let inLineComment = false;
+    let inMultilineString = false;
+    let inString = false;
+    for (let index = 0; index < offset; index += 1) {
+        const character = source[index];
+        const pair = source.slice(index, index + 2);
+        const triple = source.slice(index, index + 3);
+        if (inLineComment) {
+            if (character === '\n')
+                inLineComment = false;
+            continue;
+        }
+        if (blockCommentDepth > 0) {
+            if (pair === '/*') {
+                blockCommentDepth += 1;
+                index += 1;
+            }
+            else if (pair === '*/') {
+                blockCommentDepth -= 1;
+                index += 1;
+            }
+            continue;
+        }
+        if (inMultilineString) {
+            if (triple === '"""') {
+                inMultilineString = false;
+                index += 2;
+            }
+            continue;
+        }
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (character === '\\')
+                escaped = true;
+            else if (character === '"')
+                inString = false;
+            continue;
+        }
+        if (pair === '//') {
+            inLineComment = true;
+            index += 1;
+        }
+        else if (pair === '/*') {
+            blockCommentDepth = 1;
+            index += 1;
+        }
+        else if (triple === '"""') {
+            inMultilineString = true;
+            index += 2;
+        }
+        else if (character === '"') {
+            inString = true;
+        }
+    }
+    return !inLineComment && blockCommentDepth === 0 && !inMultilineString && !inString;
+}
+export function parseUniqueSwiftBinaryTargetChecksum(source, targetName, expectedUrl) {
+    const expression = new RegExp(`^\\s*package\\.targets\\s*\\+=\\s*\\[\\s*\\.binaryTarget\\(\\s*name:\\s*"${escapeRegExp(targetName)}"\\s*,\\s*url:\\s*"${escapeRegExp(expectedUrl)}"\\s*,\\s*checksum:\\s*"(?<checksum>[a-f0-9]{64})"\\s*\\)\\s*\\]\\s*$`, 'gm');
+    const matches = [...source.matchAll(expression)].filter((match) => match.index !== undefined && isSwiftCodeOffset(source, match.index));
+    return matches.length === 1 ? matches[0]?.groups?.checksum : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -170,6 +170,26 @@
       "import": "./dist/workspace-gates/index.mjs",
       "default": "./dist/workspace-gates/index.mjs"
     },
+    "./nuget-central-version": {
+      "types": "./dist/nuget-central-version/index.d.mts",
+      "import": "./dist/nuget-central-version/index.mjs",
+      "default": "./dist/nuget-central-version/index.mjs"
+    },
+    "./swift-semantic-equal": {
+      "types": "./dist/swift-semantic-equal/index.d.mts",
+      "import": "./dist/swift-semantic-equal/index.mjs",
+      "default": "./dist/swift-semantic-equal/index.mjs"
+    },
+    "./swift-source-offset": {
+      "types": "./dist/swift-source-offset/index.d.mts",
+      "import": "./dist/swift-source-offset/index.mjs",
+      "default": "./dist/swift-source-offset/index.mjs"
+    },
+    "./swift-resolved-pin-delta": {
+      "types": "./dist/swift-resolved-pin-delta/index.d.mts",
+      "import": "./dist/swift-resolved-pin-delta/index.mjs",
+      "default": "./dist/swift-resolved-pin-delta/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {