@foss.global/codefeed 5.1.0 → 5.3.0

package/ts/forgeinventory.client.ts

@@ -1,4 +1,4 @@
-import type * as transport from './forgeinventory.transport.js';
+import * as transport from './forgeinventory.transport.js';
 import * as validation from './forgeinventory.validation.js';
 
 export interface IForgeRequestMetrics {
@@ -32,11 +32,56 @@ export interface IForgeJsonResponse {
   headers: transport.IForgeTransportResponse['headers'];
 }
 
+export interface IForgeBytesRequestOptions {
+  signal?: AbortSignal;
+  /** Optional lower response-body budget for this request. */
+  maxResponseBytes?: number;
+  /** Additional request headers. */
+  headers?: Record<string, string>;
+  /** Sent as `accept`; the response may carry any content type, which the caller checks. */
+  accept: string;
+}
+
+export interface IForgeBytesResponse {
+  /** The response body exactly as it arrived. */
+  bytes: Buffer;
+  /** The response's media type without parameters, lowercased; null when it sent none. */
+  mediaType: string | null;
+  headers: transport.IForgeTransportResponse['headers'];
+}
+
+/** A redirect a read returned instead of refusing: never followed, its body discarded. */
+export interface IForgeRedirectResponse {
+  /** One of 301, 302, 303, 307 and 308. */
+  status: number;
+  /** The `Location` header verbatim; null when the response sent none. */
+  location: string | null;
+}
+
+/** The answer of `requestBytesOrRedirect`: the body of a 200, or the redirect. */
+export type TForgeBytesOrRedirect = ({ kind: 'bytes' } & IForgeBytesResponse) | ({ kind: 'redirect' } & IForgeRedirectResponse);
+
+interface IReadOptions {
+  signal?: AbortSignal;
+  maxResponseBytes?: number;
+  headers?: Record<string, string>;
+  accept: string;
+  /** The media type the response must carry, checked before its body is read; any when absent. */
+  requiredMediaType?: string;
+  body?: { mediaType: string; bytes: Uint8Array<ArrayBuffer> };
+  /** `return` resolves a redirect status as `redirect` instead of rejecting; defaults to `refuse`. */
+  redirect?: transport.TForgeRedirectMode;
+}
+
+type TReadResult =
+  | { kind: 'bytes'; bytes: Buffer; headers: transport.IForgeTransportResponse['headers'] }
+  | ({ kind: 'redirect' } & IForgeRedirectResponse);
+
 /**
- * One bounded, credential-scoped JSON read at a time, a GET or a POST with a
- * JSON body: a per-request deadline, a response-size budget and a strict JSON
- * content type. Failures surface as
- * `ForgeInventoryError` codes that never contain bodies, URLs or credentials.
+ * One bounded, credential-scoped read at a time, a GET or a POST with a JSON
+ * body: a per-request deadline, a response-size budget and, for JSON, a
+ * strict content type. Failures surface as `ForgeInventoryError` codes that
+ * never contain bodies, URLs or credentials.
  */
 export class ForgeRequestClient {
   readonly #options: IForgeRequestClientOptions;
@@ -49,6 +94,46 @@ export class ForgeRequestClient {
   public get metrics(): IForgeRequestMetrics { return { ...this.#metrics }; }
 
   public async request(url: URL, requestArg: IForgeRequestOptions = {}): Promise<IForgeJsonResponse> {
+    const mediaType = requestArg.mediaType ?? 'application/json';
+    const response = await this.#body(url, {
+      signal: requestArg.signal, maxResponseBytes: requestArg.maxResponseBytes, headers: requestArg.headers, accept: mediaType, requiredMediaType: mediaType,
+      ...(requestArg.json === undefined ? {} : { body: { mediaType, bytes: new TextEncoder().encode(JSON.stringify(requestArg.json)) } }),
+    });
+    try {
+      return { body: JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(response.bytes)) as unknown, headers: response.headers };
+    } catch {
+      throw new validation.ForgeInventoryError('request-or-json-failed');
+    }
+  }
+
+  /** A GET whose body is returned as the bytes that arrived, with the media type the response declared. */
+  public async requestBytes(url: URL, requestArg: IForgeBytesRequestOptions): Promise<IForgeBytesResponse> {
+    const response = await this.#body(url, requestArg);
+    return { bytes: response.bytes, mediaType: mediaTypeOf(response.headers), headers: response.headers };
+  }
+
+  /**
+   * A GET like `requestBytes`, except that a redirect status resolves as
+   * `{ kind: 'redirect', status, location }` instead of rejecting. The
+   * redirect is never followed and its body is discarded unread; any status
+   * other than 200 and a redirect still rejects with `http-<status>`.
+   */
+  public async requestBytesOrRedirect(url: URL, requestArg: IForgeBytesRequestOptions): Promise<TForgeBytesOrRedirect> {
+    const response = await this.#read(url, { ...requestArg, redirect: 'return' });
+    return response.kind === 'redirect'
+      ? response
+      : { kind: 'bytes', bytes: response.bytes, mediaType: mediaTypeOf(response.headers), headers: response.headers };
+  }
+
+  /** A read that refuses redirects, so it always answers a body. */
+  async #body(url: URL, requestArg: Omit<IReadOptions, 'redirect'>): Promise<{ bytes: Buffer; headers: transport.IForgeTransportResponse['headers'] }> {
+    const response = await this.#read(url, requestArg);
+    // The transport refuses every redirect status in this mode, so a redirect never arrives here.
+    if (response.kind === 'redirect') throw new validation.ForgeInventoryError('request-or-json-failed');
+    return response;
+  }
+
+  async #read(url: URL, requestArg: IReadOptions): Promise<TReadResult> {
     const { signal } = requestArg;
     const maxBytes = requestArg.maxResponseBytes ?? this.#options.maxResponseBytes;
     if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new validation.ForgeInventoryError('invalid-response-budget');
@@ -61,14 +146,20 @@ export class ForgeRequestClient {
     let bodyChunks: AsyncIterator<Uint8Array> | undefined;
     try {
       this.#metrics.requests++;
-      const mediaType = requestArg.mediaType ?? 'application/json';
-      const requestBody = requestArg.json === undefined ? undefined : new TextEncoder().encode(JSON.stringify(requestArg.json));
-      const headers = { accept: mediaType, ...(requestBody ? { 'content-type': mediaType } : {}), ...requestArg.headers, ...this.#options.headers };
-      const response = await this.#options.transport(url, headers, controller.signal, requestBody);
+      const headers = {
+        accept: requestArg.accept, ...(requestArg.body ? { 'content-type': requestArg.body.mediaType } : {}), ...requestArg.headers, ...this.#options.headers,
+      };
+      const response = await this.#options.transport(url, headers, controller.signal, requestArg.body?.bytes, { redirect: requestArg.redirect ?? 'refuse' });
       bodyChunks = response.body?.[Symbol.asyncIterator]();
       if (response.status === 429) this.#metrics.rateLimitedRequests++;
+      if (requestArg.redirect === 'return' && transport.redirectStatuses.has(response.status)) {
+        // The body is discarded unread by the `finally` below.
+        return { kind: 'redirect', status: response.status, location: response.headers.get('location') };
+      }
       if (response.status !== 200) throw new validation.ForgeInventoryError(`http-${response.status}`);
-      if (response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== mediaType || !bodyChunks) throw new validation.ForgeInventoryError('invalid-content-type');
+      if ((requestArg.requiredMediaType !== undefined && mediaTypeOf(response.headers) !== requestArg.requiredMediaType) || !bodyChunks) {
+        throw new validation.ForgeInventoryError('invalid-content-type');
+      }
       const chunks: Uint8Array[] = [];
       let bytes = 0;
       while (true) {
@@ -79,10 +170,8 @@ export class ForgeRequestClient {
         if (controller.signal.aborted || Date.now() >= deadline) throw new validation.ForgeInventoryError('request-aborted-or-timed-out');
         chunks.push(result.value);
       }
-      const text = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
-      const body = JSON.parse(text) as unknown;
       if (controller.signal.aborted || Date.now() >= deadline) throw new validation.ForgeInventoryError('request-aborted-or-timed-out');
-      return { body, headers: response.headers };
+      return { kind: 'bytes', bytes: Buffer.concat(chunks), headers: response.headers };
     } catch (error) {
       if (error instanceof validation.ForgeInventoryError) throw error;
       throw new validation.ForgeInventoryError(controller.signal.aborted ? 'request-aborted-or-timed-out' : 'request-or-json-failed');
@@ -93,3 +182,7 @@ export class ForgeRequestClient {
     }
   }
 }
+
+/** A response's media type without parameters, lowercased; null when it sent none. */
+const mediaTypeOf = (headersArg: transport.IForgeTransportResponse['headers']): string | null =>
+  headersArg.get('content-type')?.split(';')[0].trim().toLowerCase() || null;

package/ts/forgeinventory.transport.ts

@@ -8,16 +8,29 @@ export interface IForgeTransportResponse {
   body: AsyncIterable<Uint8Array> | null;
 }
 
+/**
+ * What a transport does with a redirect status: `refuse` rejects it, `return`
+ * resolves it as the response it is, `Location` included. Neither follows it.
+ */
+export type TForgeRedirectMode = 'refuse' | 'return';
+
+export interface IForgeTransportOptions {
+  /** Defaults to `refuse`. */
+  redirect?: TForgeRedirectMode;
+}
+
 /**
  * Sends one credential-scoped GET, or a POST of `body` when one is given, and
- * resolves once response headers arrive. A redirect status rejects and is
- * never followed; aborting `signal` discards the connection, also while the
- * body is still being read.
+ * resolves once response headers arrive. A redirect status is never followed:
+ * it rejects, unless `options.redirect` is `return`. Aborting `signal`
+ * discards the connection, also while the body is still being read.
  */
-export type TForgeTransport = (url: URL, headers: Record<string, string>, signal: AbortSignal, body?: Uint8Array<ArrayBuffer>) => Promise<IForgeTransportResponse>;
+export type TForgeTransport = (
+  url: URL, headers: Record<string, string>, signal: AbortSignal, body?: Uint8Array<ArrayBuffer>, options?: IForgeTransportOptions,
+) => Promise<IForgeTransportResponse>;
 
 /** The fetch statuses whose redirect mode `error` turns them into a network error. */
-const redirectStatuses: ReadonlySet<number> = new Set([301, 302, 303, 307, 308]);
+export const redirectStatuses: ReadonlySet<number> = new Set([301, 302, 303, 307, 308]);
 
 /**
  * Idle keep-alive sockets close after this delay, or earlier when the server
@@ -27,8 +40,10 @@ const redirectStatuses: ReadonlySet<number> = new Set([301, 302, 303, 307, 308])
 const idleSocketTimeoutMs = 4_000;
 
 /** Node's global `fetch` with the process-wide default trust store. */
-export const globalFetchTransport: TForgeTransport = async (url, headers, signal, body) => {
-  const response = await fetch(url, { method: body ? 'POST' : 'GET', headers, body, redirect: 'error', credentials: 'omit', signal });
+export const globalFetchTransport: TForgeTransport = async (url, headers, signal, body, options) => {
+  // Node's fetch answers `manual` with the redirect response itself, status and `Location` included.
+  const redirect = options?.redirect === 'return' ? 'manual' : 'error';
+  const response = await fetch(url, { method: body ? 'POST' : 'GET', headers, body, redirect, credentials: 'omit', signal });
   return { status: response.status, headers: response.headers, body: response.body };
 };
 
@@ -45,6 +60,8 @@ export interface INodeRequest {
   body?: Uint8Array | AsyncIterable<Uint8Array>;
   signal: AbortSignal;
   agents: INodeRequestAgents;
+  /** Defaults to `refuse`. */
+  redirect?: TForgeRedirectMode;
 }
 
 export interface INodeResponse extends IForgeTransportResponse {
@@ -74,9 +91,10 @@ const drained = (requestArg: InstanceType<typeof plugins.http.ClientRequest>): P
 
 /**
  * Sends one request through `node:http` or `node:https` and resolves once
- * response headers arrive. A redirect status rejects and is never followed;
- * aborting `signal` discards the connection, also while a body is still being
- * sent or read. A streamed body that fails destroys the request and rejects.
+ * response headers arrive. A redirect status is never followed: it rejects,
+ * unless `redirect` is `return`. Aborting `signal` discards the connection,
+ * also while a body is still being sent or read. A streamed body that fails
+ * destroys the request and rejects.
  */
 export const sendNodeRequest = (url: URL, requestArg: INodeRequest): Promise<INodeResponse> => new Promise<INodeResponse>((resolve, reject) => {
   const { signal } = requestArg;
@@ -126,7 +144,7 @@ export const sendNodeRequest = (url: URL, requestArg: INodeRequest): Promise<INo
   request.on('response', (response) => {
     try {
       const status = response.statusCode ?? 0;
-      if (redirectStatuses.has(status)) throw new Error('Refused redirect.');
+      if (redirectStatuses.has(status) && requestArg.redirect !== 'return') throw new Error('Refused redirect.');
       // Same combination rules as fetch: repeated fields join with ", ".
       const responseHeaders = new Headers();
       for (let index = 0; index < response.rawHeaders.length; index += 2) {
@@ -149,8 +167,10 @@ export const sendNodeRequest = (url: URL, requestArg: INodeRequest): Promise<INo
  */
 export const createHttpsTransport = (caCertificates: string[]): TForgeTransport => {
   const agents = createNodeAgents(caCertificates);
-  return async (url, headers, signal, body) => {
-    const { sent: _sent, ...response } = await sendNodeRequest(url, { method: body ? 'POST' : 'GET', headers, body, signal, agents });
+  return async (url, headers, signal, body, options) => {
+    const { sent: _sent, ...response } = await sendNodeRequest(url, {
+      method: body ? 'POST' : 'GET', headers, body, signal, agents, redirect: options?.redirect,
+    });
     return response;
   };
 };

package/ts/giteasourceinventory.packages.ts

@@ -0,0 +1,160 @@
+import * as plugins from './plugins.js';
+import * as validation from './forgeinventory.validation.js';
+
+type TMeasure = plugins.fossInterfaces.data.TForgeSourceMeasure;
+type IPackageRef = plugins.fossInterfaces.data.IForgeSourcePackageRef;
+type IPackageRecord = plugins.fossInterfaces.data.IForgeSourcePackageInventory;
+type IPackageContent = plugins.fossInterfaces.data.IForgeSourcePackageContent;
+type IPackageContentSelection = plugins.fossInterfaces.data.IForgeSourcePackageContentSelection;
+type IPackageContentGroup = plugins.fossInterfaces.data.IForgeSourcePackageContentGroup;
+type IPackageContentTotals = plugins.fossInterfaces.data.IForgeSourcePackageContentTotals;
+
+/** Media types Gitea serves an index or a manifest list as; an index candidate must be one of them. */
+export const containerIndexMediaTypes: readonly string[] = Object.freeze([
+  'application/vnd.oci.image.index.v1+json',
+  'application/vnd.docker.distribution.manifest.list.v2+json',
+]);
+
+/** Every manifest media type Gitea serves: images, indexes and manifest lists, OCI and Docker. */
+export const containerManifestMediaTypes: readonly string[] = Object.freeze([
+  ...containerIndexMediaTypes,
+  'application/vnd.oci.image.manifest.v1+json',
+  'application/vnd.docker.distribution.manifest.v2+json',
+]);
+
+/** A package type as Gitea names it; it names reason paths, so it must be one of Gitea's plain identifiers. */
+export const packageTypePattern = /^[a-z][a-z0-9_-]{0,31}$/;
+
+/** Gitea's npm name rule (`modules/packages/npm/creator.go`): `name` or `@scope/name`, URL-safe as it stands. */
+const npmNamePattern = /^(?:@[a-z0-9-][a-z0-9-._]*\/)?[a-z0-9-][a-z0-9-._]*$/;
+/** Gitea's Cargo crate name rule (`modules/packages/cargo/parser.go`). */
+const cargoNamePattern = /^[A-Za-z][A-Za-z0-9-_]{0,63}$/;
+/** Gitea's Swift scope and name rules (`routers/api/packages/swift/swift.go`); it stores the package as `scope.name`. */
+const swiftPackagePattern = /^([A-Za-z0-9][A-Za-z0-9-]{0,38})\.([A-Za-z0-9][A-Za-z0-9-_]{0,99})$/;
+
+const compareText = (aArg: string, bArg: string): number => (aArg < bArg ? -1 : aArg > bArg ? 1 : 0);
+
+/** The key of a package within one instance: owner, type and name, which Gitea keeps unique (the name without case). */
+export const packageKey = (refArg: IPackageRef): string => `${refArg.owner}/${refArg.type}/${refArg.name}`;
+
+/** Orders packages by owner, type and name in code-unit order. */
+export const comparePackages = (aArg: IPackageRef, bArg: IPackageRef): number =>
+  compareText(aArg.owner, bArg.owner) || compareText(aArg.type, bArg.type) || compareText(aArg.name, bArg.name);
+
+/** The path segment(s) of an npm package in Gitea's npm registry: the name unencoded, as Gitea's npm routes match it. */
+export const npmPackagePath = (nameArg: string): string => {
+  if (!npmNamePattern.test(nameArg) || nameArg.length > 214) throw new validation.ForgeInventoryError('invalid-npm-name');
+  return nameArg;
+};
+
+/** The path of a crate's entry in the Cargo sparse index, lowercased, per the Cargo registry index layout. */
+export const cargoIndexPath = (nameArg: string): string => {
+  if (!cargoNamePattern.test(nameArg)) throw new validation.ForgeInventoryError('invalid-cargo-name');
+  const name = nameArg.toLowerCase();
+  if (name.length === 1) return `1/${name}`;
+  if (name.length === 2) return `2/${name}`;
+  if (name.length === 3) return `3/${name[0]}/${name}`;
+  return `${name.slice(0, 2)}/${name.slice(2, 4)}/${name}`;
+};
+
+/** The scope and name of a Swift package stored as `scope.name`. */
+export const swiftPackageParts = (nameArg: string): { scope: string; name: string } => {
+  const match = swiftPackagePattern.exec(nameArg);
+  if (!match) throw new validation.ForgeInventoryError('invalid-swift-name');
+  return { scope: match[1], name: match[2] };
+};
+
+/**
+ * The digest of the manifest a container version holds: `sha256:` and the
+ * SHA-256 of the blob holding the version's `manifest.json`; null for a
+ * version without one.
+ */
+export const containerManifestDigest = (packageArg: IPackageRecord, versionIdArg: string): string | null => {
+  const blob = packageArg.blobs.find((blobArg) => blobArg.files.some((fileArg) => fileArg.versionId === versionIdArg && fileArg.name === 'manifest.json'));
+  return blob ? `sha256:${blob.sha256}` : null;
+};
+
+/**
+ * The version ids of a package's tagged-and-referenced selection: for a
+ * container package the tagged versions and the versions holding a manifest
+ * a tagged index references; every version of any other type.
+ */
+export const taggedAndReferencedVersionIds = (packageArg: IPackageRecord): Set<string> => {
+  if (packageArg.type !== 'container') return new Set(packageArg.versions.map((versionArg) => versionArg.id));
+  const tagged = packageArg.versions.filter((versionArg) => !versionArg.version.startsWith('sha256:'));
+  const referenced = new Set(tagged.flatMap((versionArg) => versionArg.references ?? []));
+  const selected = new Set(tagged.map((versionArg) => versionArg.id));
+  for (const version of packageArg.versions) {
+    const digest = containerManifestDigest(packageArg, version.id);
+    if (digest !== null && referenced.has(digest)) selected.add(version.id);
+  }
+  return selected;
+};
+
+interface IContentSum {
+  blobs: Map<string, bigint>;
+}
+
+const contentMeasure = (sumArg: IContentSum, missingArg: number): IPackageContent => {
+  const blobs = BigInt(sumArg.blobs.size);
+  const bytes = [...sumArg.blobs.values()].reduce((totalArg, sizeArg) => totalArg + sizeArg, 0n);
+  if (missingArg === 0) return { blobs: { status: 'complete', value: blobs.toString() }, bytes: { status: 'complete', value: bytes.toString() } };
+  const reason = `Package units not measured: ${missingArg}.`;
+  const partial = (valueArg: bigint): TMeasure => ({ status: 'partial', observedValue: valueArg.toString(), reason });
+  return { blobs: partial(blobs), bytes: partial(bytes) };
+};
+
+/** Distinct content of a set of package records over both selections; `missingArg` packages of the set were not read. */
+const selection = (packagesArg: readonly IPackageRecord[], missingArg: number): IPackageContentSelection => {
+  const all: IContentSum = { blobs: new Map() };
+  const tagged: IContentSum = { blobs: new Map() };
+  for (const record of packagesArg) {
+    const selected = taggedAndReferencedVersionIds(record);
+    for (const blob of record.blobs) {
+      const size = BigInt(blob.size);
+      all.blobs.set(blob.sha256, size);
+      if (blob.files.some((fileArg) => selected.has(fileArg.versionId))) tagged.blobs.set(blob.sha256, size);
+    }
+  }
+  return { allVersions: contentMeasure(all, missingArg), taggedAndReferenced: contentMeasure(tagged, missingArg) };
+};
+
+/** A group of packages with its content by type; `refsArg` are the group's discovered packages. */
+const group = (refsArg: readonly IPackageRef[], recordsArg: ReadonlyMap<string, IPackageRecord>): IPackageContentGroup => {
+  const read = (refs: readonly IPackageRef[]) => refs.flatMap((refArg) => {
+    const record = recordsArg.get(packageKey(refArg));
+    return record ? [record] : [];
+  });
+  const missing = (refs: readonly IPackageRef[]) => refs.filter((refArg) => !recordsArg.has(packageKey(refArg))).length;
+  const types = [...new Set(refsArg.map((refArg) => refArg.type))].sort(compareText);
+  return {
+    ...selection(read(refsArg), missing(refsArg)),
+    types: types.map((typeArg) => {
+      const refs = refsArg.filter((refArg) => refArg.type === typeArg);
+      return { type: typeArg, ...selection(read(refs), missing(refs)) };
+    }),
+  };
+};
+
+/**
+ * The distinct content of an inventory's packages, `totals.packageContent`:
+ * a pure function of the discovered packages and the records their units
+ * returned. Every SHA-256 counts once per scope, globally and per owner, each
+ * by type, over all versions and over the tagged versions with the manifests
+ * their indexes reference. A measure is complete only when every discovered
+ * package of its scope has a record; otherwise it is partial with the sum of
+ * the records read. Records of packages discovery does not list are ignored.
+ */
+export const composeGiteaPackageContent = (
+  discoveredArg: readonly IPackageRef[],
+  packagesArg: readonly IPackageRecord[],
+): IPackageContentTotals => {
+  const discovered = new Set(discoveredArg.map(packageKey));
+  const records = new Map(packagesArg.filter((recordArg) => discovered.has(packageKey(recordArg))).map((recordArg) => [packageKey(recordArg), recordArg]));
+  const refs = [...new Map(discoveredArg.map((refArg) => [packageKey(refArg), { owner: refArg.owner, type: refArg.type, name: refArg.name }])).values()];
+  const owners = [...new Set(refs.map((refArg) => refArg.owner))].sort(compareText);
+  return {
+    global: group(refs, records),
+    owners: owners.map((ownerArg) => ({ owner: ownerArg, ...group(refs.filter((refArg) => refArg.owner === ownerArg), records) })),
+  };
+};

package/ts/giteasourcetransfer.documents.ts

@@ -0,0 +1,97 @@
+import * as plugins from './plugins.js';
+import * as validation from './forgeinventory.validation.js';
+
+/**
+ * Package metadata documents that are JSON, which `canonicalPackageDocument`
+ * brings into one form: an npm version document, Swift release metadata, a
+ * crate version's line of the Cargo sparse index, and `{"description":…}`
+ * of a crate's latest version as the Cargo search serves it.
+ */
+export type TGiteaCanonicalPackageDocumentKind = 'npm-version' | 'swift-release' | 'cargo-index-entry' | 'cargo-description';
+
+export interface IGiteaCanonicalPackageDocument {
+  /** The canonical JSON, UTF-8. */
+  bytes: Buffer;
+  /** Lowercase hex SHA-256 of `bytes`. */
+  sha256: string;
+}
+
+/**
+ * The top-level member each kind removes: state the forge changes without
+ * replacing the version, which the source inventory records apart (a Cargo
+ * version's `yanked`, an npm version's `deprecated`).
+ */
+const mutableStateMembers: Readonly<Record<TGiteaCanonicalPackageDocumentKind, string | null>> = Object.freeze({
+  'npm-version': 'deprecated',
+  'swift-release': null,
+  'cargo-index-entry': 'yanked',
+  'cargo-description': null,
+});
+
+/**
+ * Orders two strings by Unicode code point. UTF-16 code-unit order (the
+ * default sort) differs from it where a surrogate pair meets U+E000 to U+FFFF.
+ */
+const compareCodePoints = (leftArg: string, rightArg: string): number => {
+  let left = 0;
+  let right = 0;
+  while (left < leftArg.length && right < rightArg.length) {
+    const leftPoint = leftArg.codePointAt(left)!;
+    const rightPoint = rightArg.codePointAt(right)!;
+    if (leftPoint !== rightPoint) return leftPoint - rightPoint;
+    left += leftPoint > 0xffff ? 2 : 1;
+    right += rightPoint > 0xffff ? 2 : 1;
+  }
+  return (leftArg.length - left) - (rightArg.length - right);
+};
+
+/** Compact JSON with object keys in code-point order at every depth, arrays in order and only safe integers as numbers. */
+const canonicalJson = (valueArg: unknown): string => {
+  if (valueArg === null || typeof valueArg === 'boolean' || typeof valueArg === 'string') return JSON.stringify(valueArg);
+  if (typeof valueArg === 'number') {
+    if (!Number.isSafeInteger(valueArg)) throw new validation.ForgeInventoryError('document-not-canonical');
+    return JSON.stringify(valueArg);
+  }
+  if (Array.isArray(valueArg)) return `[${valueArg.map(canonicalJson).join(',')}]`;
+  const record = valueArg as Record<string, unknown>;
+  return `{${Object.keys(record).sort(compareCodePoints).map((keyArg) => `${JSON.stringify(keyArg)}:${canonicalJson(record[keyArg])}`).join(',')}}`;
+};
+
+/**
+ * The canonical form of a package metadata document and its SHA-256, which a
+ * consumer records and compares instead of the bytes Gitea served: Gitea 28
+ * writes JSON objects held in maps (a crate's `features`, npm's maps) in a
+ * different key order on every read, and documents carry state that changes
+ * without a new version. In this order: decode as UTF-8 (fatal), parse as a
+ * JSON object, remove the kind's top-level mutable-state member (`yanked`
+ * for `cargo-index-entry`, `deprecated` for `npm-version`), and write it
+ * compact, object keys sorted by code point at every depth, arrays in their
+ * order, strings and safe integers as `JSON.stringify` writes them. Anything
+ * else, a number that is not a safe integer included, rejects with
+ * `document-not-canonical`; an unknown kind with
+ * `package-document-kind-invalid`. The same document gives the same bytes
+ * whatever order its keys arrived in.
+ */
+export const canonicalPackageDocument = (kindArg: TGiteaCanonicalPackageDocumentKind, bytesArg: Uint8Array): IGiteaCanonicalPackageDocument => {
+  if (!Object.hasOwn(mutableStateMembers, kindArg)) throw new validation.ForgeInventoryError('package-document-kind-invalid');
+  let canonical: string;
+  try {
+    const parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytesArg)) as unknown;
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new validation.ForgeInventoryError('document-not-canonical');
+    const member = mutableStateMembers[kindArg];
+    if (member !== null) delete (parsed as Record<string, unknown>)[member];
+    canonical = canonicalJson(parsed);
+  } catch {
+    // Invalid UTF-8 or JSON, a non-object, an unsafe number, or nesting deeper than the stack.
+    throw new validation.ForgeInventoryError('document-not-canonical');
+  }
+  const bytes = Buffer.from(canonical, 'utf8');
+  return { bytes, sha256: plugins.crypto.createHash('sha256').update(bytes).digest('hex') };
+};
+
+/**
+ * A Swift version as Gitea keys an alternate manifest (`Package@swift-<v>.swift`),
+ * trimmed by its `TrimmedVersionString`: major and minor, and the patch only
+ * when it is not zero.
+ */
+export const swiftManifestVersionPattern = /^(?:0|[1-9]\d{0,17})\.(?:0|[1-9]\d{0,17})(?:\.[1-9]\d{0,17})?$/;

package/ts/index.ts

@@ -491,3 +491,6 @@ export * from './classes.giteasourceinventory.js';
 export * from './classes.giteasourcetransfer.js';
 export * from './classes.lfsbatchclient.js';
 export { GitScratchBudget, mirrorScratchBytes } from './giteasourceinventory.git.js';
+export { composeGiteaPackageContent } from './giteasourceinventory.packages.js';
+export { canonicalPackageDocument } from './giteasourcetransfer.documents.js';
+export type { IGiteaCanonicalPackageDocument, TGiteaCanonicalPackageDocumentKind } from './giteasourcetransfer.documents.js';

package/ts/plugins.ts

@@ -1,4 +1,4 @@
-import type * as fossInterfaces from '@foss.global/interfaces';
+import * as fossInterfaces from '@foss.global/interfaces';
 
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs/promises';
@@ -20,7 +20,7 @@ export {
 import * as lik from '@push.rocks/lik';
 import * as smarttime from '@push.rocks/smarttime';
 
-export type { fossInterfaces };
+export { fossInterfaces };
 export type TNpmRegistry = import('@push.rocks/smartnpm').NpmRegistry;
 export type TGitManager = import('@foss.global/gitmanager').GitManager;
 export type TGitManagerCommitSummary = import('@foss.global/gitmanager').IGitManagerCommitSummary;