@foss.global/codefeed 2.1.0 → 3.0.0

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@foss.global/codefeed',
-  version: '2.1.0',
+  version: '3.0.0',
   description: 'The @foss.global/codefeed module generates commit/activity feeds from forge providers including Gitea and GitManager.'
 }

package/ts/classes.giteasourceinventory.ts

@@ -1,8 +1,9 @@
-import type * as plugins from './plugins.js';
+import * as plugins from './plugins.js';
 import * as transport from './forgeinventory.transport.js';
 import * as validation from './forgeinventory.validation.js';
 import { ForgeRequestClient } from './forgeinventory.client.js';
 import type { IForgeRequestMetrics, IForgeRequestOptions } from './forgeinventory.client.js';
+import { measureGiteaMirror } from './giteasourceinventory.git.js';
 
 type TMeasure = plugins.fossInterfaces.data.TForgeSourceMeasure;
 type TUnit = plugins.fossInterfaces.data.TForgeSourceInventoryUnit;
@@ -24,8 +25,17 @@ export interface IGiteaSourceInventoryOptions {
    * sent only to `baseUrl` and never appears in results, reasons or errors.
    */
   token: string;
-  /** PEM certificates that replace the default trust store for this reader's connections. */
+  /** PEM certificates that replace the default trust store for this reader's connections, Git transfers included. */
   caCertificates?: string[];
+  /**
+   * Absolute path of a private directory for temporary mirrors. Each
+   * repository is cloned into it with every ref, measured at the Git level and
+   * removed again, so it needs room for the largest repositories measured at
+   * the same time.
+   */
+  gitWorkDir: string;
+  /** Wall-clock limit of one repository's mirror clone; defaults to 30 minutes, at most six hours. */
+  gitTimeoutMs?: number;
   /** Items requested per page; Gitea caps it at its `MAX_RESPONSE_ITEMS`. */
   pageSize?: number;
   /** Pages read per listing before the listing counts as partial. */
@@ -66,8 +76,6 @@ export const giteaSourceInventoryLimitations: readonly string[] = [
   'Gitea has no read that lists user-scoped Actions secrets; they are reissued.',
 ];
 
-const lfsNotMeasured: TMeasure = { status: 'notMeasured', reason: 'Gitea exposes no API that lists LFS objects.' };
-
 const complete = (valueArg: bigint | number): TMeasure => ({ status: 'complete', value: BigInt(valueArg).toString() });
 const partial = (observedArg: bigint | number, reasonArg: string): TMeasure => ({ status: 'partial', observedValue: BigInt(observedArg).toString(), reason: reasonArg });
 const notMeasured = (reasonArg: string): TMeasure => ({ status: 'notMeasured', reason: reasonArg });
@@ -143,19 +151,28 @@ const unitKey = (unitArg: TUnit): string => unitArg.kind === 'instance' ? 'insta
 const compareText = (aArg: string, bArg: string): number => aArg < bArg ? -1 : aArg > bArg ? 1 : 0;
 
 /**
- * Authenticated, read-only inventory of a Gitea instance through its REST API,
- * read with a site administrator's token. It only sends GET requests, counts
- * secrets and variables without retaining their values, and reports every
- * read that did not finish as a partial or unmeasured value instead of a count.
+ * Authenticated, read-only inventory of a Gitea instance, read with a site
+ * administrator's token: GET requests to its REST API, a mirror clone of every
+ * repository for refs, objects and LFS pointers, and LFS batch `download`
+ * requests that check which referenced objects Gitea holds. It counts secrets
+ * and variables without retaining their values, and reports every read that
+ * did not finish as a partial or unmeasured value instead of a count.
  */
 export class GiteaSourceInventory {
-  readonly #options: { instanceId: string; baseUrl: string; pageSize: number; maxPages: number };
+  readonly #options: {
+    instanceId: string; baseUrl: string; pageSize: number; maxPages: number; requestTimeoutMs: number; maxResponseBytes: number;
+    token: string; caCertificates?: string[]; gitWorkDir: string; gitTimeoutMs: number;
+  };
+  readonly #transport: transport.TForgeTransport;
   readonly #client: ForgeRequestClient;
+  #lfsClient: ForgeRequestClient | null = null;
+  #readerLogin: Promise<string> | null = null;
 
   constructor(optionsArg: IGiteaSourceInventoryOptions) {
     const baseUrl = validation.httpUrl(optionsArg.baseUrl);
     if (!baseUrl || !baseUrl.startsWith('https:') || typeof optionsArg.instanceId !== 'string' || !optionsArg.instanceId.trim() ||
-      typeof optionsArg.token !== 'string' || !optionsArg.token || /[\s\u0000-\u001f\u007f]/.test(optionsArg.token)) {
+      typeof optionsArg.token !== 'string' || !optionsArg.token || /[\s\u0000-\u001f\u007f]/.test(optionsArg.token) ||
+      typeof optionsArg.gitWorkDir !== 'string' || !plugins.path.isAbsolute(optionsArg.gitWorkDir)) {
       throw new validation.ForgeInventoryError('invalid-options');
     }
     const limits = {
@@ -163,17 +180,22 @@ export class GiteaSourceInventory {
       maxPages: optionsArg.maxPages ?? 10_000,
       requestTimeoutMs: optionsArg.requestTimeoutMs ?? 60_000,
       maxResponseBytes: optionsArg.maxResponseBytes ?? 16 * 1024 * 1024,
+      gitTimeoutMs: optionsArg.gitTimeoutMs ?? 30 * 60 * 1000,
     };
     for (const [name, maximum] of [
-      ['pageSize', 100], ['maxPages', 1_000_000], ['requestTimeoutMs', 300_000], ['maxResponseBytes', 64 * 1024 * 1024],
+      ['pageSize', 100], ['maxPages', 1_000_000], ['requestTimeoutMs', 300_000], ['maxResponseBytes', 64 * 1024 * 1024], ['gitTimeoutMs', 6 * 60 * 60 * 1000],
     ] as const) {
       const value = limits[name];
       if (!Number.isSafeInteger(value) || value < 1 || value > maximum) throw new validation.ForgeInventoryError('invalid-limits');
     }
-    this.#options = { instanceId: optionsArg.instanceId, baseUrl: baseUrl.replace(/\/+$/, ''), pageSize: limits.pageSize, maxPages: limits.maxPages };
+    const caCertificates = optionsArg.caCertificates === undefined ? undefined : validation.caCertificates(optionsArg.caCertificates);
+    this.#options = {
+      instanceId: optionsArg.instanceId, baseUrl: baseUrl.replace(/\/+$/, ''), ...limits,
+      token: optionsArg.token, caCertificates, gitWorkDir: optionsArg.gitWorkDir,
+    };
+    this.#transport = caCertificates === undefined ? transport.globalFetchTransport : transport.createHttpsTransport(caCertificates);
     this.#client = new ForgeRequestClient({
-      transport: optionsArg.caCertificates === undefined ? transport.globalFetchTransport
-        : transport.createHttpsTransport(validation.caCertificates(optionsArg.caCertificates)),
+      transport: this.#transport,
       headers: { authorization: `token ${optionsArg.token}` },
       requestTimeoutMs: limits.requestTimeoutMs,
       maxResponseBytes: limits.maxResponseBytes,
@@ -183,7 +205,16 @@ export class GiteaSourceInventory {
   /** Validated, normalized instance root; contains no credentials or API suffix. */
   public get baseUrl(): string { return this.#options.baseUrl; }
 
-  public get metrics(): IForgeRequestMetrics { return this.#client.metrics; }
+  /** REST and LFS batch requests together. */
+  public get metrics(): IForgeRequestMetrics {
+    const rest = this.#client.metrics;
+    const lfs = this.#lfsClient?.metrics ?? { requests: 0, responseBytes: 0, rateLimitedRequests: 0 };
+    return {
+      requests: rest.requests + lfs.requests,
+      responseBytes: rest.responseBytes + lfs.responseBytes,
+      rateLimitedRequests: rest.rateLimitedRequests + lfs.rateLimitedRequests,
+    };
+  }
 
   /**
    * Identifies the source and its reader and lists every owner and repository.
@@ -455,8 +486,7 @@ export class GiteaSourceInventory {
       objectFormat: requiredString(item.object_format_name),
       defaultBranch: requiredString(item.default_branch),
       features,
-      git: await this.#git(path, item, empty, signalArg),
-      lfs: { objects: lfsNotMeasured, bytes: lfsNotMeasured },
+      ...await this.#git(ownerArg, nameArg, item, signalArg),
       collaboration: await this.#collaboration(path, features, signalArg),
       // Releases stay readable while their unit is disabled; a disabled wiki answers 404.
       releases: await this.#releases(path, signalArg),
@@ -486,28 +516,39 @@ export class GiteaSourceInventory {
     }
   }
 
-  async #git(pathArg: string, itemArg: Record<string, unknown>, emptyArg: boolean, signalArg?: AbortSignal): Promise<IRepository['git']> {
-    const reportedSizeKiB = complete(BigInt(validation.decimal(itemArg.size)));
-    if (emptyArg) return { reportedSizeKiB, branches: complete(0), tags: complete(0), pullRequestRefs: complete(0), otherRefs: complete(0) };
-    try {
-      const refs = (await this.#get(`${pathArg}/git/refs`, { signal: signalArg })).body;
-      if (!Array.isArray(refs)) throw new validation.ForgeInventoryError('invalid-page');
-      const counts = { branches: 0, tags: 0, pullRequestRefs: 0, otherRefs: 0 };
-      for (const refArg of refs) {
-        const ref = requiredString(validation.record(refArg).ref);
-        if (ref.startsWith('refs/heads/')) counts.branches++;
-        else if (ref.startsWith('refs/tags/')) counts.tags++;
-        else if (ref.startsWith('refs/pull/')) counts.pullRequestRefs++;
-        else counts.otherRefs++;
-      }
-      return {
-        reportedSizeKiB, branches: complete(counts.branches), tags: complete(counts.tags),
-        pullRequestRefs: complete(counts.pullRequestRefs), otherRefs: complete(counts.otherRefs),
-      };
-    } catch (error) {
-      const failed = partial(0, reason(error));
-      return { reportedSizeKiB, branches: failed, tags: failed, pullRequestRefs: failed, otherRefs: failed };
+  /** Refs, objects and LFS objects, read from a mirror clone; only the reported size comes from the API. */
+  async #git(ownerArg: string, nameArg: string, itemArg: Record<string, unknown>, signalArg?: AbortSignal): Promise<Pick<IRepository, 'git' | 'lfs'>> {
+    const sizeKiB = BigInt(validation.decimal(itemArg.size));
+    const username = await this.#login(signalArg);
+    const measured = await measureGiteaMirror({
+      baseUrl: this.#options.baseUrl, owner: ownerArg, name: nameArg, username, token: this.#options.token,
+      caCertificates: this.#options.caCertificates, workDir: this.#options.gitWorkDir, reportedSizeKiB: sizeKiB,
+      timeoutMs: this.#options.gitTimeoutMs,
+      lfsClient: this.#lfs(username), signal: signalArg,
+    });
+    return { git: { reportedSizeKiB: complete(sizeKiB), ...measured.git }, lfs: measured.lfs };
+  }
+
+  /** The reader's login, the user name of its Git and LFS credentials. */
+  #login(signalArg?: AbortSignal): Promise<string> {
+    if (this.#readerLogin === null) {
+      const login = this.#get('/user', { signal: signalArg }).then((responseArg) => segment(validation.record(responseArg.body).login));
+      // A failed read is retried by the next repository.
+      login.catch(() => { if (this.#readerLogin === login) this.#readerLogin = null; });
+      this.#readerLogin = login;
     }
+    return this.#readerLogin;
+  }
+
+  /** LFS routes accept the token as a Basic password, not as a `token` authorization. */
+  #lfs(usernameArg: string): ForgeRequestClient {
+    this.#lfsClient ??= new ForgeRequestClient({
+      transport: this.#transport,
+      headers: { authorization: `Basic ${Buffer.from(`${usernameArg}:${this.#options.token}`).toString('base64')}` },
+      requestTimeoutMs: this.#options.requestTimeoutMs,
+      maxResponseBytes: this.#options.maxResponseBytes,
+    });
+    return this.#lfsClient;
   }
 
   async #collaboration(pathArg: string, featuresArg: IRepository['features'], signalArg?: AbortSignal): Promise<IRepository['collaboration']> {
@@ -834,8 +875,9 @@ export const composeGiteaSourceInventory = (
         empty: repositoryCount((repositoryArg) => repositoryArg.empty),
         withWiki: sumMeasures([...repositories.map((repositoryArg) => indicator(repositoryArg.wikiPages, (valueArg) => valueArg > 0n)), ...missingRepositories]),
       },
-      git: sumGroup(repositories.map((repositoryArg) => repositoryArg.git), ['reportedSizeKiB', 'branches', 'tags', 'pullRequestRefs', 'otherRefs'], missingRepositories),
-      lfs: sumGroup(repositories.map((repositoryArg) => repositoryArg.lfs), ['objects', 'bytes'], missingRepositories),
+      git: sumGroup(repositories.map((repositoryArg) => repositoryArg.git),
+        ['reportedSizeKiB', 'branches', 'tags', 'pullRequestRefs', 'otherRefs', 'objects', 'objectBytes'], missingRepositories),
+      lfs: sumGroup(repositories.map((repositoryArg) => repositoryArg.lfs), ['objects', 'bytes', 'missingObjects'], missingRepositories),
       collaboration: sumGroup(repositories.map((repositoryArg) => repositoryArg.collaboration),
         ['issues', 'pullRequests', 'comments', 'reviews', 'reviewComments', 'labels', 'milestones', 'reactions', 'attachments', 'attachmentBytes'], missingRepositories),
       releases: sumGroup(repositories.map((repositoryArg) => repositoryArg.releases), ['releases', 'drafts', 'assets', 'assetBytes'], missingRepositories),

package/ts/forgeinventory.client.ts

@@ -21,6 +21,10 @@ export interface IForgeRequestOptions {
   maxResponseBytes?: number;
   /** Additional request headers, such as a provider's impersonation header. */
   headers?: Record<string, string>;
+  /** JSON media type sent as `accept` and required of the response; defaults to `application/json`. */
+  mediaType?: string;
+  /** Sends this value as a JSON body of `mediaType` in a POST instead of a GET, for reads that take a request body. */
+  json?: unknown;
 }
 
 export interface IForgeJsonResponse {
@@ -29,8 +33,9 @@ export interface IForgeJsonResponse {
 }
 
 /**
- * One bounded, credential-scoped JSON GET at a time: a per-request deadline, a
- * response-size budget and a strict JSON content type. Failures surface as
+ * 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.
  */
 export class ForgeRequestClient {
@@ -56,12 +61,14 @@ export class ForgeRequestClient {
     let bodyChunks: AsyncIterator<Uint8Array> | undefined;
     try {
       this.#metrics.requests++;
-      const headers = { accept: 'application/json', ...requestArg.headers, ...this.#options.headers };
-      const response = await this.#options.transport(url, headers, controller.signal);
+      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);
       bodyChunks = response.body?.[Symbol.asyncIterator]();
       if (response.status === 429) this.#metrics.rateLimitedRequests++;
       if (response.status !== 200) throw new validation.ForgeInventoryError(`http-${response.status}`);
-      if (response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json' || !bodyChunks) throw new validation.ForgeInventoryError('invalid-content-type');
+      if (response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== mediaType || !bodyChunks) throw new validation.ForgeInventoryError('invalid-content-type');
       const chunks: Uint8Array[] = [];
       let bytes = 0;
       while (true) {

package/ts/forgeinventory.transport.ts

@@ -9,11 +9,12 @@ export interface IForgeTransportResponse {
 }
 
 /**
- * Sends one credential-scoped GET 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.
+ * 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.
  */
-export type TForgeTransport = (url: URL, headers: Record<string, string>, signal: AbortSignal) => Promise<IForgeTransportResponse>;
+export type TForgeTransport = (url: URL, headers: Record<string, string>, signal: AbortSignal, body?: Uint8Array<ArrayBuffer>) => 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]);
@@ -26,8 +27,8 @@ 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) => {
-  const response = await fetch(url, { method: 'GET', headers, redirect: 'error', credentials: 'omit', signal });
+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 });
   return { status: response.status, headers: response.headers, body: response.body };
 };
 
@@ -38,10 +39,10 @@ export const globalFetchTransport: TForgeTransport = async (url, headers, signal
  */
 export const createHttpsTransport = (caCertificates: string[]): TForgeTransport => {
   const agent = new plugins.https.Agent({ ca: caCertificates, keepAlive: true, timeout: idleSocketTimeoutMs });
-  return (url, headers, signal) => new Promise<IForgeTransportResponse>((resolve, reject) => {
+  return (url, headers, signal, body) => new Promise<IForgeTransportResponse>((resolve, reject) => {
     if (signal.aborted) return reject(signal.reason);
     // Bodies are read as sent, so ask for them without a content coding.
-    const request = plugins.https.request(url, { method: 'GET', headers: { ...headers, 'accept-encoding': 'identity' }, agent });
+    const request = plugins.https.request(url, { method: body ? 'POST' : 'GET', headers: { ...headers, 'accept-encoding': 'identity' }, agent });
     // Stays attached for the request's lifetime, so a connection failure while
     // the body is read never becomes an unhandled 'error' event.
     request.on('error', reject);
@@ -68,6 +69,6 @@ export const createHttpsTransport = (caCertificates: string[]): TForgeTransport
         request.destroy();
       }
     });
-    request.end();
+    request.end(body);
   });
 };

package/ts/giteasourceinventory.git.ts

@@ -0,0 +1,316 @@
+import * as plugins from './plugins.js';
+import * as validation from './forgeinventory.validation.js';
+import type { ForgeRequestClient } from './forgeinventory.client.js';
+
+type TMeasure = plugins.fossInterfaces.data.TForgeSourceMeasure;
+type IGitCounts = Omit<plugins.fossInterfaces.data.IForgeSourceGitCounts, 'reportedSizeKiB'>;
+type ILfsCounts = plugins.fossInterfaces.data.IForgeSourceLfsCounts;
+
+export interface IGiteaMirrorSource {
+  /** Instance root without a trailing slash. */
+  baseUrl: string;
+  owner: string;
+  name: string;
+  /** The reader's login and token; Gitea accepts a token as the Basic password for Git and LFS. */
+  username: string;
+  token: string;
+  caCertificates?: string[];
+  /** Private directory that holds the temporary mirror. */
+  workDir: string;
+  /** The repository size Gitea reports, which sizes the mirror's scratch reservation. */
+  reportedSizeKiB: bigint;
+  /** Wall-clock limit of the mirror clone. */
+  timeoutMs: number;
+  /** Sends LFS batch reads with the reader's Basic credentials. */
+  lfsClient: ForgeRequestClient;
+  signal?: AbortSignal;
+}
+
+/** Objects per LFS batch request. */
+const lfsBatchSize = 100;
+const lfsMediaType = 'application/vnd.git-lfs+json';
+
+/**
+ * Scratch space reserved for one mirror: twice the size Gitea reports, because
+ * a clone holds received and indexed packs, plus fixed headroom for refs, the
+ * index and a size Gitea has not updated yet.
+ */
+export const mirrorScratchBytes = (reportedSizeKiBArg: bigint): bigint => reportedSizeKiBArg * 1024n * 2n + 64n * 1024n * 1024n;
+
+/** Bytes an unprivileged process may still write to the file system holding `directoryArg`. */
+const statfsFreeBytes = async (directoryArg: string): Promise<bigint> => {
+  const stats = await plugins.fs.statfs(directoryArg, { bigint: true });
+  return stats.bavail * stats.bsize;
+};
+
+/**
+ * Admits mirror clones on one file system in arrival order while the scratch
+ * they reserve fits its free space. A clone's reservation counts in full until
+ * it is released, although part of it is already written, so the check never
+ * admits more than fits. A clone that does not fit waits until the clones in
+ * flight release their reservations; one that does not fit even alone is
+ * refused.
+ */
+export class GitScratchBudget {
+  readonly #freeBytes: (directoryArg: string) => Promise<bigint>;
+  #reserved = 0n;
+  /** Settles when the clones ahead of the next arrival have been admitted or refused. */
+  #queue: Promise<void> = Promise.resolve();
+  readonly #releaseListeners = new Set<() => void>();
+
+  constructor(freeBytesArg: (directoryArg: string) => Promise<bigint> = statfsFreeBytes) {
+    this.#freeBytes = freeBytesArg;
+  }
+
+  /**
+   * Reserves `bytesArg` in `directoryArg` and resolves with the function that
+   * releases them, or with null when they exceed the free space with no other
+   * clone in flight. Rejects when the free space cannot be read or `signalArg`
+   * aborts.
+   */
+  async reserve(directoryArg: string, bytesArg: bigint, signalArg?: AbortSignal): Promise<(() => void) | null> {
+    const ahead = this.#queue;
+    let admitted!: () => void;
+    const turn = new Promise<void>((resolve) => { admitted = resolve; });
+    // Followers wait for this turn and every turn ahead of it, even when this one ends early.
+    this.#queue = ahead.then(() => turn);
+    try {
+      await this.#until(ahead, signalArg);
+      for (;;) {
+        // Listens before reading the free space, so a release while it is read is not missed.
+        let listener!: () => void;
+        const released = new Promise<void>((resolve) => { listener = resolve; });
+        this.#releaseListeners.add(listener);
+        try {
+          const free = await this.#freeBytes(directoryArg);
+          if (this.#reserved + bytesArg <= free) {
+            this.#reserved += bytesArg;
+            return this.#releaser(bytesArg);
+          }
+          if (this.#reserved === 0n) return null;
+          await this.#until(released, signalArg);
+        } finally {
+          this.#releaseListeners.delete(listener);
+        }
+      }
+    } finally {
+      admitted();
+    }
+  }
+
+  #releaser(bytesArg: bigint): () => void {
+    let held = true;
+    return () => {
+      if (!held) return;
+      held = false;
+      this.#reserved -= bytesArg;
+      for (const listener of this.#releaseListeners) listener();
+    };
+  }
+
+  async #until(promiseArg: Promise<void>, signalArg?: AbortSignal): Promise<void> {
+    signalArg?.throwIfAborted();
+    if (!signalArg) return promiseArg;
+    let abort!: () => void;
+    const aborted = new Promise<never>((_resolve, reject) => {
+      abort = () => reject(signalArg.reason);
+      signalArg.addEventListener('abort', abort, { once: true });
+    });
+    try {
+      await Promise.race([promiseArg, aborted]);
+    } finally {
+      signalArg.removeEventListener('abort', abort);
+    }
+  }
+}
+
+/** One budget per file system, shared by every reader in the process. */
+const scratchBudgets = new Map<bigint, GitScratchBudget>();
+
+const scratchBudget = async (workDirArg: string): Promise<GitScratchBudget> => {
+  const device = (await plugins.fs.stat(workDirArg, { bigint: true })).dev;
+  let budget = scratchBudgets.get(device);
+  if (!budget) {
+    budget = new GitScratchBudget();
+    scratchBudgets.set(device, budget);
+  }
+  return budget;
+};
+
+const complete = (valueArg: bigint | number): TMeasure => ({ status: 'complete', value: BigInt(valueArg).toString() });
+const partial = (observedArg: bigint | number, reasonArg: string): TMeasure => ({ status: 'partial', observedValue: BigInt(observedArg).toString(), reason: reasonArg });
+
+const failedGit = (reasonArg: string): IGitCounts => {
+  const failed = partial(0, reasonArg);
+  return { branches: failed, tags: failed, pullRequestRefs: failed, otherRefs: failed, objects: failed, objectBytes: failed };
+};
+const failedLfs = (reasonArg: string): ILfsCounts => {
+  const failed = partial(0, reasonArg);
+  return { objects: failed, bytes: failed, missingObjects: failed };
+};
+
+/**
+ * Fixed reason for a failed step. GitManager errors are never passed on: they
+ * are redacted, but still remote text.
+ */
+const stepFailure = (errorArg: unknown, stepArg: string, signalArg?: AbortSignal): string =>
+  signalArg?.aborted ? 'request-aborted' : errorArg instanceof validation.ForgeInventoryError ? errorArg.code : stepArg;
+
+/**
+ * Measures one repository at the Git level: clones every ref Gitea advertises
+ * into a temporary mirror, counts its refs and objects, finds the LFS pointers
+ * of every reachable revision and checks through the LFS batch API which of
+ * their objects Gitea holds. The mirror is removed afterwards. The clone starts
+ * only once its scratch reservation fits the work directory's free space; a
+ * repository too large for it fails with `git-workdir-too-small`.
+ */
+export const measureGiteaMirror = async (sourceArg: IGiteaMirrorSource): Promise<{ git: IGitCounts; lfs: ILfsCounts }> => {
+  const { signal } = sourceArg;
+  if (signal?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+  let release: (() => void) | null;
+  try {
+    release = await (await scratchBudget(sourceArg.workDir)).reserve(sourceArg.workDir, mirrorScratchBytes(sourceArg.reportedSizeKiB), signal);
+  } catch {
+    const failure = signal?.aborted ? 'request-aborted' : 'git-workdir-failed';
+    return { git: failedGit(failure), lfs: failedLfs(failure) };
+  }
+  if (release === null) return { git: failedGit('git-workdir-too-small'), lfs: failedLfs('git-workdir-too-small') };
+  try {
+    return await measureReservedMirror(sourceArg);
+  } finally {
+    release();
+  }
+};
+
+const measureReservedMirror = async (sourceArg: IGiteaMirrorSource): Promise<{ git: IGitCounts; lfs: ILfsCounts }> => {
+  const { signal } = sourceArg;
+  const { GitManager } = await plugins.getGitManager();
+  let directory: string;
+  try {
+    directory = await plugins.fs.mkdtemp(plugins.path.join(sourceArg.workDir, 'mirror-'));
+  } catch {
+    return { git: failedGit('git-workdir-failed'), lfs: failedLfs('git-workdir-failed') };
+  }
+  const manager = new GitManager({ dataDir: directory });
+  // Stopping the engine ends the operation in flight.
+  const abort = () => { void manager.stop().catch(() => undefined); };
+  signal?.addEventListener('abort', abort, { once: true });
+  const selector = { org: 'source', repo: 'mirror' };
+  try {
+    try {
+      // An abort while the engine module loaded or the directory was created reached no listener.
+      signal?.throwIfAborted();
+      await manager.start();
+      await manager.importMirror({
+        ...selector,
+        remoteUrl: `${sourceArg.baseUrl}/${encodeURIComponent(sourceArg.owner)}/${encodeURIComponent(sourceArg.name)}.git`,
+        credential: { kind: 'basic', username: sourceArg.username, password: sourceArg.token },
+        caCertificates: sourceArg.caCertificates,
+        timeoutMs: sourceArg.timeoutMs,
+      });
+    } catch (error) {
+      const failure = stepFailure(error, 'git-mirror-failed', signal);
+      return { git: failedGit(failure), lfs: failedLfs(failure) };
+    }
+    const git = await measureRefsAndObjects(manager, selector, signal);
+    let pointers: Array<{ oid: string; sizeBytes: number }>;
+    try {
+      pointers = await manager.listRepositoryLfsPointers(selector);
+    } catch (error) {
+      return { git, lfs: failedLfs(stepFailure(error, 'lfs-pointer-scan-failed', signal)) };
+    }
+    return { git, lfs: await giteaLfsPresence(sourceArg, pointers) };
+  } finally {
+    signal?.removeEventListener('abort', abort);
+    await manager.stop().catch(() => undefined);
+    await plugins.fs.rm(directory, { recursive: true, force: true });
+  }
+};
+
+const measureRefsAndObjects = async (
+  managerArg: plugins.TGitManager,
+  selectorArg: { org: string; repo: string },
+  signalArg?: AbortSignal,
+): Promise<IGitCounts> => {
+  const counts = { branches: 0, tags: 0, pullRequestRefs: 0, otherRefs: 0 };
+  let refsFailure: string | null = null;
+  try {
+    let cursor: string | undefined;
+    do {
+      const page = await managerArg.listRefs({ ...selectorArg, cursor });
+      // Nothing writes to the private mirror, so a changed inventory is a failure.
+      if (page.status === 'stale') throw new validation.ForgeInventoryError('git-refs-changed');
+      for (const ref of page.refs) {
+        if (ref.name.startsWith('refs/heads/')) counts.branches++;
+        else if (ref.name.startsWith('refs/tags/')) counts.tags++;
+        else if (ref.name.startsWith('refs/pull/')) counts.pullRequestRefs++;
+        else counts.otherRefs++;
+      }
+      cursor = page.pagination.status === 'more' ? page.pagination.cursor : undefined;
+    } while (cursor !== undefined);
+  } catch (error) {
+    refsFailure = stepFailure(error, 'git-refs-failed', signalArg);
+  }
+  const refs = (valueArg: number) => refsFailure === null ? complete(valueArg) : partial(0, refsFailure);
+  let objects: TMeasure;
+  let objectBytes: TMeasure;
+  try {
+    const size = await managerArg.getRepositorySize(selectorArg);
+    objects = complete(size.objectCount);
+    objectBytes = complete(size.objectBytes);
+  } catch (error) {
+    objects = objectBytes = partial(0, stepFailure(error, 'git-size-failed', signalArg));
+  }
+  return {
+    branches: refs(counts.branches), tags: refs(counts.tags), pullRequestRefs: refs(counts.pullRequestRefs), otherRefs: refs(counts.otherRefs),
+    objects, objectBytes,
+  };
+};
+
+/**
+ * Asks Gitea's LFS batch API, as a `download`, which referenced objects it
+ * holds: a held object answers with a download action, a missing one with
+ * error 404. Actions, their URLs and headers are never retained.
+ */
+export const giteaLfsPresence = async (
+  sourceArg: Pick<IGiteaMirrorSource, 'baseUrl' | 'owner' | 'name' | 'lfsClient' | 'signal'>,
+  pointersArg: Array<{ oid: string; sizeBytes: number }>,
+): Promise<ILfsCounts> => {
+  const url = new URL(`${sourceArg.baseUrl}/${encodeURIComponent(sourceArg.owner)}/${encodeURIComponent(sourceArg.name)}.git/info/lfs/objects/batch`);
+  let held = 0n;
+  let heldBytes = 0n;
+  let missing = 0n;
+  for (let index = 0; index < pointersArg.length; index += lfsBatchSize) {
+    const chunk = pointersArg.slice(index, index + lfsBatchSize);
+    try {
+      const response = await sourceArg.lfsClient.request(url, {
+        signal: sourceArg.signal,
+        mediaType: lfsMediaType,
+        json: { operation: 'download', transfers: ['basic'], objects: chunk.map((pointerArg) => ({ oid: pointerArg.oid, size: pointerArg.sizeBytes })) },
+      });
+      const objects = validation.record(response.body).objects;
+      if (!Array.isArray(objects) || objects.length !== chunk.length) throw new validation.ForgeInventoryError('invalid-lfs-batch');
+      const requested = new Map(chunk.map((pointerArg) => [pointerArg.oid, pointerArg.sizeBytes]));
+      for (const objectArg of objects) {
+        const object = validation.record(objectArg);
+        const size = typeof object.oid === 'string' ? requested.get(object.oid) : undefined;
+        if (size === undefined || object.size !== size) throw new validation.ForgeInventoryError('invalid-lfs-batch');
+        requested.delete(object.oid as string);
+        const download = object.actions === undefined || object.actions === null ? undefined : validation.record(object.actions).download;
+        if (download !== undefined && download !== null && object.error === undefined) {
+          held++;
+          heldBytes += BigInt(size);
+        } else if (object.error !== undefined && validation.record(object.error).code === 404) {
+          missing++;
+        } else {
+          // A size that disagrees with the stored object answers 422.
+          throw new validation.ForgeInventoryError('lfs-object-unavailable');
+        }
+      }
+    } catch (error) {
+      const failure = stepFailure(error, 'lfs-batch-failed', sourceArg.signal);
+      return { objects: partial(held, failure), bytes: partial(heldBytes, failure), missingObjects: partial(missing, failure) };
+    }
+  }
+  return { objects: complete(held), bytes: complete(heldBytes), missingObjects: complete(missing) };
+};

package/ts/plugins.ts

@@ -1,8 +1,10 @@
 import type * as fossInterfaces from '@foss.global/interfaces';
 
 import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
 import * as https from 'node:https';
-export { crypto, https };
+import * as path from 'node:path';
+export { crypto, fs, https, path };
 
 // module
 import * as interfaces from './interfaces/index.js';
@@ -25,6 +27,7 @@ export type TGitManagerTag = import('@foss.global/gitmanager').IGitManagerTag;
 export type TGitManagerDiff = import('@foss.global/gitmanager').IGitManagerDiff;
 
 export const getSmartnpm = async () => import('@push.rocks/smartnpm');
+export const getGitManager = async () => import('@foss.global/gitmanager');
 
 export {
   smarttime,