@foss.global/codefeed 1.11.1 → 1.13.0

package/ts/classes.forgeinventory.ts

@@ -0,0 +1,378 @@
+import * as plugins from './plugins.js';
+import * as validation from './forgeinventory.validation.js';
+
+export { ForgeInventoryError } from './forgeinventory.validation.js';
+
+export interface IForgeInventoryOptions {
+  kind: 'gitea' | 'gitlab';
+  instanceId: string;
+  /** Instance root, including an optional deployment subpath. HTTPS is required. */
+  baseUrl: string;
+  /** Personal access token, retained only in this adapter's memory. */
+  token?: string;
+  pageSize?: number;
+  maxPages?: number;
+  requestTimeoutMs?: number;
+  maxResponseBytes?: number;
+}
+
+export interface IForgeInventoryRequest {
+  cursor?: string;
+  signal?: AbortSignal;
+  /** Optional lower response-body budget for this request. */
+  maxResponseBytes?: number;
+}
+
+export interface IForgeInventoryMetrics {
+  requests: number;
+  responseBytes: number;
+  rateLimitedRequests: number;
+}
+
+export type TForgeInventoryVersionInspection =
+  | { status: 'observed'; version: string; observation: plugins.fossInterfaces.data.IForgeInventoryObservation }
+  | { status: 'unverified'; reason: string; observation: plugins.fossInterfaces.data.IForgeInventoryObservation };
+
+type TCollection = 'repositories' | 'namespaces' | 'namespaceDirectory';
+interface IContinuation {
+  version: 2;
+  collection: TCollection;
+  /** Endpoint page, reset when a directory moves from organizations to users. */
+  page: number;
+  /** Completed requests across every endpoint in this collection. */
+  pagesRead: number;
+  phase: 'organizations' | 'users' | null;
+  after: string | null;
+}
+
+/** Read-only, caller-visible API observations. This adapter never claims admin completeness. */
+export class ForgeInventoryAdapter {
+  readonly #options: Required<Omit<IForgeInventoryOptions, 'token'>> & { token?: string };
+  readonly #cursorKey = plugins.crypto.randomBytes(32);
+  readonly #metrics: IForgeInventoryMetrics = { requests: 0, responseBytes: 0, rateLimitedRequests: 0 };
+
+  constructor(optionsArg: IForgeInventoryOptions) {
+    const baseUrl = validation.httpUrl(optionsArg.baseUrl);
+    if (!baseUrl || !baseUrl.startsWith('https:') || !optionsArg.instanceId.trim() ||
+      !['gitea', 'gitlab'].includes(optionsArg.kind) ||
+      (optionsArg.token !== undefined && (!optionsArg.token || /[\s\u0000-\u001f\u007f]/.test(optionsArg.token)))) {
+      throw new validation.ForgeInventoryError('invalid-options');
+    }
+    this.#options = {
+      ...optionsArg,
+      baseUrl: baseUrl.replace(/\/$/, ''),
+      pageSize: optionsArg.pageSize ?? 50,
+      maxPages: optionsArg.maxPages ?? 1000,
+      requestTimeoutMs: optionsArg.requestTimeoutMs ?? 30_000,
+      maxResponseBytes: optionsArg.maxResponseBytes ?? 8 * 1024 * 1024,
+    };
+    for (const [name, maximum] of [
+      ['pageSize', 100], ['maxPages', 100_000], ['requestTimeoutMs', 300_000], ['maxResponseBytes', 64 * 1024 * 1024],
+    ] as const) {
+      const value = this.#options[name];
+      if (!Number.isSafeInteger(value) || value < 1 || value > maximum) throw new validation.ForgeInventoryError('invalid-limits');
+    }
+  }
+
+  public get instance(): plugins.fossInterfaces.data.IForgeInventoryInstance {
+    return { instanceId: this.#options.instanceId, kind: this.#options.kind, version: null };
+  }
+
+  public get metrics(): IForgeInventoryMetrics { return { ...this.#metrics }; }
+
+  public observation(startedAt: string): plugins.fossInterfaces.data.IForgeInventoryObservation {
+    return {
+      startedAt, finishedAt: new Date().toISOString(),
+      access: this.#options.token ? 'callerVisible' : 'publicOnly', consistency: { status: 'live' },
+    };
+  }
+
+  public listRepositories(requestArg: IForgeInventoryRequest = {}): Promise<plugins.fossInterfaces.data.IForgeInventoryPage<plugins.fossInterfaces.data.IForgeInventoryRepository>> {
+    return this.page('repositories', (item) => this.repository(item), requestArg);
+  }
+
+  /** Organizations/groups only. User namespaces are not enumerated by these endpoints. */
+  public listNamespaces(requestArg: IForgeInventoryRequest = {}): Promise<plugins.fossInterfaces.data.IForgeInventoryPage<plugins.fossInterfaces.data.IForgeInventoryNamespace>> {
+    return this.page('namespaces', (item) => this.namespace(item), requestArg);
+  }
+
+  /** Gitea admin organizations/users or GitLab caller-visible group/personal namespaces. */
+  public async listNamespaceDirectory(requestArg: IForgeInventoryRequest = {}): Promise<plugins.fossInterfaces.data.IForgeInventoryPage<plugins.fossInterfaces.data.IForgeInventoryNamespace>> {
+    if (!this.#options.token) throw new validation.ForgeInventoryError('namespace-directory-requires-token');
+    return this.page('namespaceDirectory', (item, state) => this.directoryNamespace(item, state), requestArg);
+  }
+
+  /** A fresh, bounded observation; failures never retain a previously observed version. */
+  public async inspectVersion(requestArg: Omit<IForgeInventoryRequest, 'cursor'> = {}): Promise<TForgeInventoryVersionInspection> {
+    const startedAt = new Date().toISOString();
+    try {
+      const { body } = await this.request(new URL(`${this.#options.baseUrl}/api/${this.#options.kind === 'gitea' ? 'v1' : 'v4'}/version`), requestArg);
+      const version = validation.record(body).version;
+      // Preserve release suffixes while rejecting arbitrary bodies, URLs and control characters.
+      if (typeof version !== 'string' || version.length > 128 || !/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9][A-Za-z0-9.+-]*)?$/.test(version)) {
+        throw new validation.ForgeInventoryError('invalid-server-version');
+      }
+      return { status: 'observed', version, observation: this.observation(startedAt) };
+    } catch (error) {
+      return {
+        status: 'unverified', observation: this.observation(startedAt),
+        reason: error instanceof validation.ForgeInventoryError ? error.message : 'Version inspection failed.',
+      };
+    }
+  }
+
+  private identity(idNamespace: string, value: unknown): plugins.fossInterfaces.data.TForgeInventoryIdentity {
+    const objectId = validation.decimal(value);
+    if (objectId === '0') throw new validation.ForgeInventoryError('invalid-identity');
+    return { status: 'identified', ref: { instanceId: this.#options.instanceId, idNamespace, objectId, parentObjectId: null } };
+  }
+
+  private namespace(itemArg: unknown): plugins.fossInterfaces.data.IForgeInventoryNamespace {
+    const item = validation.record(itemArg);
+    if (this.#options.kind === 'gitea') {
+      const pathSegments = validation.segments(item.name);
+      if (pathSegments.length !== 1) throw new validation.ForgeInventoryError('invalid-organization-path');
+      return {
+        identity: this.identity('gitea.user.id', item.id), kind: 'organization', parent: null,
+        location: { pathSegments, webUrl: null },
+        visibility: validation.visibility(item.visibility === 'limited' ? 'internal' : item.visibility),
+      };
+    }
+    return {
+      identity: this.identity('gitlab.group.id', item.id), kind: 'group',
+      parent: item.parent_id === null ? null : item.parent_id === undefined
+        ? { status: 'unresolved', reason: 'Parent group was not exposed.' }
+        : this.identity('gitlab.group.id', item.parent_id),
+      location: { pathSegments: validation.segments(item.full_path), webUrl: validation.httpUrl(item.web_url) },
+      visibility: validation.visibility(item.visibility),
+    };
+  }
+
+  private directoryNamespace(itemArg: unknown, state: IContinuation): plugins.fossInterfaces.data.IForgeInventoryNamespace {
+    const item = validation.record(itemArg);
+    if (this.#options.kind === 'gitea') {
+      if (state.phase === 'organizations') return this.namespace(item);
+      const pathSegments = validation.segments(item.login);
+      if (pathSegments.length !== 1) throw new validation.ForgeInventoryError('invalid-user-namespace-path');
+      return {
+        identity: this.identity('gitea.user.id', item.id), kind: 'user', parent: null,
+        location: { pathSegments, webUrl: validation.httpUrl(item.html_url) },
+        visibility: validation.visibility(item.visibility === 'limited' ? 'internal' : item.visibility),
+      };
+    }
+    if (item.kind === 'group') return this.namespace(item);
+    if (item.kind !== 'user') throw new validation.ForgeInventoryError('invalid-namespace-kind');
+    const pathSegments = validation.segments(item.full_path);
+    if (pathSegments.length !== 1 || (item.parent_id !== undefined && item.parent_id !== null)) {
+      throw new validation.ForgeInventoryError('invalid-user-namespace-parent');
+    }
+    return {
+      identity: this.identity('gitlab.namespace.id', item.id), kind: 'user', parent: null,
+      location: { pathSegments, webUrl: validation.httpUrl(item.web_url) },
+      visibility: validation.visibility(item.visibility),
+    };
+  }
+
+  private repository(itemArg: unknown): plugins.fossInterfaces.data.IForgeInventoryRepository {
+    const item = validation.record(itemArg);
+    if (this.#options.kind === 'gitea') {
+      const owner = validation.record(item.owner);
+      const pathSegments = [...validation.segments(owner.login), ...validation.segments(item.name)];
+      if (pathSegments.length !== 2) throw new validation.ForgeInventoryError('invalid-repository-path');
+      const privateRepo = validation.optionalBoolean(item.private);
+      const internalRepo = validation.optionalBoolean(item.internal);
+      return {
+        identity: this.identity('gitea.repository.id', item.id), namespace: this.identity('gitea.user.id', owner.id),
+        location: { pathSegments, webUrl: validation.httpUrl(item.html_url) },
+        description: validation.optionalString(item.description),
+        visibility: privateRepo === true ? 'private' : internalRepo === true ? 'internal' : privateRepo === false && internalRepo === false ? 'public' : null,
+        archived: validation.optionalBoolean(item.archived), defaultBranch: validation.optionalString(item.default_branch),
+        httpCloneUrl: validation.httpUrl(item.clone_url), sshCloneUrl: validation.sshUrl(item.ssh_url),
+        gitSizeBytes: validation.unknownSize('Gitea size is not a separate Git byte measurement.'),
+      };
+    }
+    const namespace = validation.record(item.namespace);
+    if (namespace.kind !== 'group' && namespace.kind !== 'user') throw new validation.ForgeInventoryError('invalid-namespace-kind');
+    return {
+      identity: this.identity('gitlab.project.id', item.id),
+      namespace: this.identity(namespace.kind === 'group' ? 'gitlab.group.id' : 'gitlab.namespace.id', namespace.id),
+      location: { pathSegments: validation.segments(item.path_with_namespace), webUrl: validation.httpUrl(item.web_url) },
+      description: validation.optionalString(item.description), visibility: validation.visibility(item.visibility),
+      archived: validation.optionalBoolean(item.archived), defaultBranch: validation.optionalString(item.default_branch),
+      httpCloneUrl: validation.httpUrl(item.http_url_to_repo), sshCloneUrl: validation.sshUrl(item.ssh_url_to_repo),
+      gitSizeBytes: validation.gitlabSize(item.statistics),
+    };
+  }
+
+  private url(state: IContinuation): URL {
+    const gitea = this.#options.kind === 'gitea';
+    const endpoint = state.collection === 'repositories' ? (gitea ? 'repos/search' : 'projects')
+      : state.collection === 'namespaceDirectory' ? (gitea ? `admin/${state.phase === 'organizations' ? 'orgs' : 'users'}` : 'namespaces')
+      : (gitea ? 'orgs' : 'groups');
+    const url = new URL(`${this.#options.baseUrl}/api/${gitea ? 'v1' : 'v4'}/${endpoint}`);
+    url.searchParams.set(gitea ? 'limit' : 'per_page', String(this.#options.pageSize));
+    if (gitea) {
+      url.searchParams.set('page', String(state.page));
+      if (state.collection === 'repositories') {
+        url.searchParams.set('sort', 'id'); url.searchParams.set('order', 'asc'); url.searchParams.set('private', 'true');
+      }
+    } else if (state.collection === 'namespaceDirectory') {
+      url.searchParams.set('page', String(state.page));
+    } else {
+      url.searchParams.set('order_by', 'id'); url.searchParams.set('sort', 'asc');
+      if (state.collection === 'repositories') {
+        url.searchParams.set('pagination', 'keyset'); url.searchParams.set('statistics', 'true');
+        if (state.after) url.searchParams.set('id_after', state.after);
+      } else {
+        url.searchParams.set('all_available', 'true'); url.searchParams.set('page', String(state.page));
+      }
+    }
+    return url;
+  }
+
+  private cursor(state: IContinuation): string {
+    const payload = Buffer.from(JSON.stringify(state)).toString('base64url');
+    return `${payload}.${plugins.crypto.createHmac('sha256', this.#cursorKey).update(payload).digest('base64url')}`;
+  }
+
+  private continuation(collection: TCollection, cursor?: string): IContinuation {
+    const directory = collection === 'namespaceDirectory' && this.#options.kind === 'gitea';
+    if (cursor === undefined) return { version: 2, collection, page: 1, pagesRead: 0, phase: directory ? 'organizations' : null, after: null };
+    try {
+      if (cursor.length > 2048) throw new Error();
+      const [payload, signature, extra] = cursor.split('.');
+      const expected = plugins.crypto.createHmac('sha256', this.#cursorKey).update(payload).digest('base64url');
+      if (extra !== undefined || !signature || signature.length !== expected.length ||
+        !plugins.crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) throw new Error();
+      const state = JSON.parse(Buffer.from(payload, 'base64url').toString()) as IContinuation;
+      if (state.version !== 2 || state.collection !== collection || !Number.isSafeInteger(state.page) ||
+        !Number.isSafeInteger(state.pagesRead) || state.pagesRead < 1 || state.pagesRead >= this.#options.maxPages ||
+        state.page < 1 || state.page > state.pagesRead + 1 ||
+        (directory ? state.phase !== 'organizations' && state.phase !== 'users' : state.phase !== null) ||
+        ((collection !== 'repositories' || this.#options.kind !== 'gitlab') && state.after !== null) ||
+        (state.after !== null && validation.decimal(state.after) !== state.after)) throw new Error();
+      return state;
+    } catch { throw new validation.ForgeInventoryError('invalid-cursor'); }
+  }
+
+  private async page<TItem>(collection: TCollection, map: (value: unknown, state: IContinuation) => TItem, requestArg: IForgeInventoryRequest): Promise<plugins.fossInterfaces.data.IForgeInventoryPage<TItem>> {
+    const state = this.continuation(collection, requestArg.cursor);
+    const startedAt = new Date().toISOString();
+    const url = this.url(state);
+    const { body, headers } = await this.request(url, requestArg);
+    let rows: unknown = body;
+    if (this.#options.kind === 'gitea' && collection === 'repositories') {
+      const envelope = validation.record(body);
+      if (envelope.ok !== true) throw new validation.ForgeInventoryError('search-not-successful');
+      rows = envelope.data;
+    }
+    if (!Array.isArray(rows) || rows.length > this.#options.pageSize) throw new validation.ForgeInventoryError('invalid-page');
+    const items = rows.map((item) => map(item, state));
+    let pagination: plugins.fossInterfaces.data.TForgeInventoryPagination;
+    try {
+      const next = this.next(state, url, headers, rows);
+      pagination = next === null ? { status: 'exhausted' } : state.pagesRead + 1 >= this.#options.maxPages
+        ? { status: 'incomplete', reason: 'Configured page limit reached.' }
+        : { status: 'more', cursor: this.cursor(next) };
+    } catch {
+      pagination = { status: 'incomplete', reason: 'Invalid or inconsistent pagination metadata.' };
+    }
+    return { schemaVersion: 1, instance: this.instance, scope: { kind: 'instance' }, observation: this.observation(startedAt), items, pagination };
+  }
+
+  private next(state: IContinuation, current: URL, headers: Headers, rows: unknown[]): IContinuation | null {
+    const keyset = this.#options.kind === 'gitlab' && state.collection === 'repositories';
+    let previousId = BigInt(state.after ?? '0');
+    if (keyset) for (const row of rows) {
+      const id = BigInt(validation.decimal(validation.record(row).id));
+      if (id <= previousId) throw new Error();
+      previousId = id;
+    }
+    const link = headers.get('link');
+    let nextUrl: URL | null = null;
+    if (link !== null) {
+      if (link.length > 16_384) throw new Error();
+      for (const entry of link.split(',')) {
+        const match = entry.trim().match(/^<([^<>]+)>;\s*rel="(next|prev|first|last)"$/);
+        if (!match) throw new Error();
+        if (match[2] !== 'next') continue;
+        if (nextUrl !== null) throw new Error();
+        nextUrl = new URL(match[1], current);
+        if (nextUrl.origin !== current.origin || nextUrl.pathname !== current.pathname || nextUrl.username || nextUrl.password || nextUrl.hash) throw new Error();
+        const expected = new URL(current);
+        const changing = keyset ? 'id_after' : 'page';
+        expected.searchParams.delete(changing);
+        const actual = new URL(nextUrl);
+        if (actual.searchParams.getAll(changing).length !== 1) throw new Error();
+        actual.searchParams.delete(changing);
+        expected.searchParams.sort(); actual.searchParams.sort();
+        if (expected.search !== actual.search) throw new Error();
+      }
+    }
+    const xNext = headers.get('x-next-page');
+    if (!keyset && xNext !== null && xNext !== '' && validation.decimal(xNext) !== String(state.page + 1)) throw new Error();
+    if (rows.length === 0) {
+      if (nextUrl || xNext) throw new Error();
+      if (state.phase === 'organizations') return { ...state, phase: 'users', page: 1, pagesRead: state.pagesRead + 1 };
+      return null;
+    }
+    if (keyset) {
+      if (!nextUrl) return null; // GitLab keyset exhaustion is signalled by no next Link.
+      const after = validation.decimal(nextUrl.searchParams.get('id_after'));
+      if (after !== previousId.toString()) throw new Error();
+      return { ...state, page: state.page + 1, pagesRead: state.pagesRead + 1, after };
+    }
+    if (nextUrl && validation.decimal(nextUrl.searchParams.get('page')) !== String(state.page + 1)) throw new Error();
+    if (nextUrl && xNext === '') throw new Error();
+    // A short page can reflect a server page-size cap. Probe the following page
+    // even without Link rather than silently truncating at that cap.
+    return { ...state, page: state.page + 1, pagesRead: state.pagesRead + 1 };
+  }
+
+  private async request(url: URL, requestArg: IForgeInventoryRequest): Promise<{ body: unknown; headers: Headers }> {
+    const { signal } = requestArg;
+    const maxBytes = requestArg.maxResponseBytes ?? this.#options.maxResponseBytes;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new validation.ForgeInventoryError('invalid-response-budget');
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    if (signal?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+    signal?.addEventListener('abort', abort, { once: true });
+    const timeout = setTimeout(abort, this.#options.requestTimeoutMs);
+    const deadline = Date.now() + this.#options.requestTimeoutMs;
+    let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+    try {
+      const headers = new Headers({ accept: 'application/json' });
+      if (this.#options.token) headers.set(this.#options.kind === 'gitea' ? 'authorization' : 'private-token',
+        this.#options.kind === 'gitea' ? `token ${this.#options.token}` : this.#options.token);
+      this.#metrics.requests++;
+      const response = await fetch(url, { method: 'GET', headers, redirect: 'error', credentials: 'omit', signal: controller.signal });
+      reader = response.body?.getReader();
+      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' || !reader) throw new validation.ForgeInventoryError('invalid-content-type');
+      const chunks: Uint8Array[] = [];
+      let bytes = 0;
+      while (true) {
+        const result = await reader.read();
+        if (result.done) break;
+        bytes += result.value.byteLength; this.#metrics.responseBytes += result.value.byteLength;
+        if (bytes > Math.min(maxBytes, this.#options.maxResponseBytes)) throw new validation.ForgeInventoryError('response-size-limit');
+        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 };
+    } 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');
+    } finally {
+      controller.abort(); clearTimeout(timeout); signal?.removeEventListener('abort', abort);
+      if (reader) {
+        try { await reader.cancel(); } catch { /* The request has already been aborted. */ }
+        reader.releaseLock();
+      }
+    }
+  }
+}

package/ts/classes.forgeinventoryscanner.ts

@@ -0,0 +1,172 @@
+import type * as plugins from './plugins.js';
+import { ForgeInventoryAdapter, ForgeInventoryError } from './classes.forgeinventory.js';
+import type { IForgeInventoryMetrics, IForgeInventoryRequest, IForgeInventoryOptions, TForgeInventoryVersionInspection } from './classes.forgeinventory.js';
+import { unknownSize } from './forgeinventory.validation.js';
+
+export interface IForgeInventoryScanOptions {
+  signal?: AbortSignal;
+  /** Maximum distinct items retained per collection. */
+  maxItems?: number;
+  /** Deadline for the complete scan, including body reads. */
+  timeoutMs?: number;
+  /** Maximum response bytes consumed across all collection and version requests. */
+  maxScanResponseBytes?: number;
+  /** Probe the server version at the beginning of this scan. Defaults to false. */
+  inspectVersion?: boolean;
+  /** Include personal namespaces through authenticated directory endpoints. Defaults to false. */
+  namespaceDirectory?: boolean;
+}
+
+export interface IForgeInventoryScan {
+  report: plugins.fossInterfaces.data.IForgeInventoryReport;
+  repositories: plugins.fossInterfaces.data.IForgeInventoryRepository[];
+  namespaces: plugins.fossInterfaces.data.IForgeInventoryNamespace[];
+  metrics: IForgeInventoryMetrics;
+  versionInspection: TForgeInventoryVersionInspection | { status: 'notInspected'; reason: string };
+}
+
+const entityClasses = {
+  namespaces: true, users: true, teams: true, memberships: true, repositories: true,
+  gitRefs: true, gitObjects: true, protectedRefs: true, publicSshKeys: true, deployKeys: true,
+  issues: true, issueComments: true, pullRequests: true, reviews: true, reviewComments: true,
+  labels: true, milestones: true, assignees: true, reactions: true, releases: true,
+  releaseAssets: true, lfsObjects: true, packages: true, packageVersions: true, packageBlobs: true,
+  webhooks: true, webhookDeliveries: true, ciWorkflows: true, ciRuns: true, ciArtifacts: true,
+  wikis: true, projects: true,
+} satisfies Record<plugins.fossInterfaces.data.TForgeInventoryEntityClass, true>;
+
+/** A bounded, disposable observation; callers own any durable storage and migration decisions. */
+export class ForgeInventoryScanner {
+  readonly #adapter: ForgeInventoryAdapter;
+  #running = false;
+
+  constructor(optionsArg: IForgeInventoryOptions) {
+    this.#adapter = new ForgeInventoryAdapter(optionsArg);
+  }
+
+  public async scan(optionsArg: IForgeInventoryScanOptions = {}): Promise<IForgeInventoryScan> {
+    const maxItems = optionsArg.maxItems ?? 100_000;
+    const timeoutMs = optionsArg.timeoutMs ?? 60_000;
+    const maxScanResponseBytes = optionsArg.maxScanResponseBytes ?? 64 * 1024 * 1024;
+    if (!Number.isSafeInteger(maxItems) || maxItems < 1 || maxItems > 1_000_000 ||
+      !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 3_600_000 ||
+      !Number.isSafeInteger(maxScanResponseBytes) || maxScanResponseBytes < 1 || maxScanResponseBytes > 1024 * 1024 * 1024) {
+      throw new ForgeInventoryError('invalid-scan-limits');
+    }
+    if ((optionsArg.inspectVersion !== undefined && typeof optionsArg.inspectVersion !== 'boolean') ||
+      (optionsArg.namespaceDirectory !== undefined && typeof optionsArg.namespaceDirectory !== 'boolean')) {
+      throw new ForgeInventoryError('invalid-scan-options');
+    }
+    if (this.#running) throw new ForgeInventoryError('scan-already-running');
+    this.#running = true;
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    if (optionsArg.signal?.aborted) controller.abort();
+    optionsArg.signal?.addEventListener('abort', abort, { once: true });
+    const timeout = setTimeout(abort, timeoutMs);
+    const before = this.#adapter.metrics;
+    const deadline = Date.now() + timeoutMs;
+    const remainingBytes = () => maxScanResponseBytes - (this.#adapter.metrics.responseBytes - before.responseBytes);
+    const collections = Object.fromEntries(Object.keys(entityClasses).map((key) => [key, {
+      capability: { status: 'unverified', reason: 'No inventory reader has inspected this entity class.' },
+      result: { status: 'notInspected', reason: 'Outside this repository and namespace scan.' },
+    }])) as plugins.fossInterfaces.data.IForgeInventoryReport['collections'];
+    try {
+      if (Date.now() >= deadline) controller.abort();
+      const versionInspection: IForgeInventoryScan['versionInspection'] = optionsArg.inspectVersion
+        ? await this.#adapter.inspectVersion({ signal: controller.signal, maxResponseBytes: remainingBytes() })
+        : { status: 'notInspected', reason: 'Server version inspection was not requested.' };
+      const namespaces = await this.collect((request) => optionsArg.namespaceDirectory
+        ? this.#adapter.listNamespaceDirectory(request) : this.#adapter.listNamespaces(request), maxItems, controller.signal, deadline, remainingBytes);
+      const repositories = await this.collect((request) => this.#adapter.listRepositories(request), maxItems, controller.signal, deadline, remainingBytes);
+      const namespaceLimitation = 'Only organization/group namespaces were inspected; personal namespaces and full private namespace coverage remain uninspected.';
+      collections.namespaces = {
+        capability: this.capability(namespaces, [
+          ...(optionsArg.namespaceDirectory ? [] : [namespaceLimitation]),
+          'Live API visibility does not prove administrator completeness.',
+          'Namespace metadata does not establish user identity or permission inventory.',
+        ]),
+        result: !optionsArg.namespaceDirectory && namespaces.result.status === 'enumerated' ? {
+          status: 'incomplete', observation: namespaces.result.observation,
+          observedCount: namespaces.result.count, reason: namespaceLimitation,
+        } : namespaces.result,
+      };
+      const repositoryResult = repositories.result;
+      if (repositoryResult.status === 'enumerated') {
+        const measurements = repositories.items.map((item) => item.gitSizeBytes);
+        repositoryResult.sizeBytes = measurements.length > 0 && measurements.every((size) => size.status === 'measured')
+          ? { status: 'measured', value: measurements.reduce((sum, size) => sum + (size.status === 'measured' ? BigInt(size.value) : 0n), 0n).toString(), accuracy: 'estimate' }
+          : unknownSize('Separate Git byte measurements were not available for every repository.');
+      }
+      collections.repositories = {
+        capability: this.capability(repositories, ['Only API-visible repositories are enumerated.', 'Live pagination is not a frozen export.', 'Git size statistics do not measure outgoing push bytes.']),
+        result: repositoryResult,
+      };
+      const after = this.#adapter.metrics;
+      return {
+        report: {
+          schemaVersion: 1,
+          instance: { ...this.#adapter.instance, version: versionInspection.status === 'observed' ? versionInspection.version : null },
+          scope: { kind: 'instance' }, collections,
+          additionalCollections: optionsArg.namespaceDirectory ? [] : [{
+            name: this.#adapter.instance.kind === 'gitea' ? 'gitea.organizations' : 'gitlab.groups',
+            capability: this.capability(namespaces, ['Endpoint visibility and live pagination limits apply.']),
+            result: namespaces.result,
+          }],
+        },
+        repositories: repositories.items, namespaces: namespaces.items, versionInspection,
+        metrics: {
+          requests: after.requests - before.requests,
+          responseBytes: after.responseBytes - before.responseBytes,
+          rateLimitedRequests: after.rateLimitedRequests - before.rateLimitedRequests,
+        },
+      };
+    } finally {
+      controller.abort(); clearTimeout(timeout); optionsArg.signal?.removeEventListener('abort', abort);
+      this.#running = false;
+    }
+  }
+
+  private capability(
+    collection: { items: unknown[]; result: plugins.fossInterfaces.data.TForgeInventoryCollectionResult }, limitations: string[],
+  ): plugins.fossInterfaces.data.TForgeInventoryCapability {
+    return collection.result.status === 'enumerated' || collection.items.length > 0
+      ? { status: 'available', limitations }
+      : { status: 'unverified', reason: 'No successful enumeration or entity observation established this reader capability.' };
+  }
+
+  private async collect<TItem extends { identity: plugins.fossInterfaces.data.TForgeInventoryIdentity }>(
+    read: (request: IForgeInventoryRequest) => Promise<plugins.fossInterfaces.data.IForgeInventoryPage<TItem>>,
+    maxItems: number, signal: AbortSignal, deadline: number, remainingBytes: () => number,
+  ): Promise<{ items: TItem[]; result: plugins.fossInterfaces.data.TForgeInventoryCollectionResult }> {
+    const startedAt = new Date().toISOString();
+    const items: TItem[] = [];
+    const identities = new Set<string>();
+    let cursor: string | undefined;
+    const incomplete = (reason: string) => ({ items, result: {
+      status: 'incomplete' as const, observation: this.#adapter.observation(startedAt), observedCount: String(items.length), reason,
+    } });
+    while (true) {
+      if (signal.aborted || Date.now() >= deadline) return incomplete('Scan aborted or deadline reached.');
+      if (remainingBytes() <= 0) return incomplete('Configured scan response-byte limit reached.');
+      let page: plugins.fossInterfaces.data.IForgeInventoryPage<TItem>;
+      try { page = await read({ cursor, signal, maxResponseBytes: remainingBytes() }); }
+      catch (error) {
+        return incomplete(error instanceof ForgeInventoryError ? error.message : 'Inventory request failed.');
+      }
+      for (const item of page.items) {
+        if (item.identity.status !== 'identified') return incomplete('Stable provider identity was not available.');
+        const key = JSON.stringify(item.identity.ref);
+        if (identities.has(key)) return incomplete('Repeated provider identity during live pagination.');
+        if (items.length >= maxItems) return incomplete('Configured item limit reached.');
+        identities.add(key); items.push(item);
+      }
+      if (signal.aborted || Date.now() >= deadline) return incomplete('Scan aborted or deadline reached.');
+      if (page.pagination.status === 'incomplete') return incomplete(page.pagination.reason);
+      if (page.pagination.status === 'exhausted') return {
+        items, result: { status: 'enumerated', observation: this.#adapter.observation(startedAt), count: String(items.length), sizeBytes: unknownSize('No byte measurement for this collection.') },
+      };
+      cursor = page.pagination.cursor;
+    }
+  }
+}

package/ts/forgeinventory.validation.ts

@@ -0,0 +1,88 @@
+import type * as plugins from './plugins.js';
+
+export class ForgeInventoryError extends Error {
+  constructor(public readonly code: string) {
+    // Codes are adapter-owned constants. Never include remote bodies or URLs.
+    super(`Forge inventory: ${code}`);
+    this.name = 'ForgeInventoryError';
+  }
+}
+
+export const record = (value: unknown): Record<string, unknown> => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new ForgeInventoryError('invalid-object');
+  }
+  return value as Record<string, unknown>;
+};
+
+export const decimal = (value: unknown): string => {
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) {
+    return String(value);
+  }
+  if (typeof value === 'string' && /^(0|[1-9][0-9]{0,99})$/.test(value)) {
+    return value;
+  }
+  throw new ForgeInventoryError('invalid-or-imprecise-integer');
+};
+
+export const optionalString = (value: unknown): string | null => {
+  if (value === undefined || value === null || value === '') return null;
+  if (typeof value !== 'string') throw new ForgeInventoryError('invalid-string');
+  return value;
+};
+
+export const optionalBoolean = (value: unknown): boolean | null => {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== 'boolean') throw new ForgeInventoryError('invalid-boolean');
+  return value;
+};
+
+export const segments = (value: unknown): string[] => {
+  const path = optionalString(value);
+  if (!path || path.split('/').some((part) => !part || part === '.' || part === '..' || /[\\\u0000-\u001f\u007f]/.test(part))) {
+    throw new ForgeInventoryError('invalid-path');
+  }
+  // Provider JSON paths are already decoded. A literal hyphen is never a separator.
+  return path.split('/');
+};
+
+export const visibility = (value: unknown): plugins.fossInterfaces.data.TForgeInventoryVisibility | null => {
+  if (value === undefined || value === null) return null;
+  if (value === 'public' || value === 'internal' || value === 'private') return value;
+  throw new ForgeInventoryError('invalid-visibility');
+};
+
+export const httpUrl = (value: unknown): string | null => {
+  const text = optionalString(value);
+  if (text === null) return null;
+  try {
+    const url = new URL(text);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error();
+    return url.href;
+  } catch {
+    throw new ForgeInventoryError('unsafe-http-url');
+  }
+};
+
+export const sshUrl = (value: unknown): string | null => {
+  const text = optionalString(value);
+  if (text === null) return null;
+  // Permit the transport username, but never a password, query, or fragment.
+  if (/^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+:[^\s?#]+$/.test(text)) return text;
+  try {
+    const url = new URL(text);
+    if (url.protocol !== 'ssh:' || url.password || url.search || url.hash) throw new Error();
+    return url.href;
+  } catch {
+    throw new ForgeInventoryError('unsafe-ssh-url');
+  }
+};
+
+export const unknownSize = (reason: string): plugins.fossInterfaces.data.TForgeInventoryQuantity => ({ status: 'unknown', reason });
+
+export const gitlabSize = (statistics: unknown): plugins.fossInterfaces.data.TForgeInventoryQuantity => {
+  if (statistics === undefined || statistics === null) return unknownSize('Repository statistics were not exposed.');
+  const size = record(statistics).repository_size;
+  if (size === undefined || size === null) return unknownSize('Repository size was not exposed.');
+  return { status: 'measured', value: decimal(size), accuracy: 'estimate' };
+};

package/ts/index.ts

@@ -485,3 +485,5 @@ export class CodeFeed {
     throw new Error(`fetchFunction failed after retries for ${urlArg}: ${lastError?.message ?? 'unknown error'}`);
   }
 }
+export * from './classes.forgeinventory.js';
+export * from './classes.forgeinventoryscanner.js';

package/ts/plugins.ts

@@ -1,5 +1,8 @@
 import type * as fossInterfaces from '@foss.global/interfaces';
 
+import * as crypto from 'node:crypto';
+export { crypto };
+
 // module
 import * as interfaces from './interfaces/index.js';