@foss.global/codefeed 1.12.0 → 1.14.0

package/ts/classes.forgeinventory.ts

@@ -29,11 +29,22 @@ export interface IForgeInventoryMetrics {
   rateLimitedRequests: number;
 }
 
-type TCollection = 'repositories' | 'namespaces';
+export type TForgeInventoryVersionInspection =
+  | { status: 'observed'; version: string; observation: plugins.fossInterfaces.data.IForgeInventoryObservation }
+  | { status: 'unverified'; reason: string; observation: plugins.fossInterfaces.data.IForgeInventoryObservation };
+
+type TRepositoryScope = Extract<plugins.fossInterfaces.data.TForgeInventoryScope, { kind: 'repository' }>;
+type TIdentifiedRepositoryScope = TRepositoryScope & { identity: Extract<plugins.fossInterfaces.data.TForgeInventoryIdentity, { status: 'identified' }> };
+type TCollection = 'repositories' | 'namespaces' | 'namespaceDirectory' | 'issues';
 interface IContinuation {
-  version: 1;
+  version: 3;
   collection: TCollection;
+  repositoryKey: string | null;
+  /** 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;
 }
 
@@ -88,12 +99,96 @@ export class ForgeInventoryAdapter {
     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);
+  }
+
+  /** All visible open/closed issues in one stable repository, excluding Gitea pull requests. */
+  public listIssues(scopeArg: TRepositoryScope, requestArg: IForgeInventoryRequest = {}): Promise<plugins.fossInterfaces.data.IForgeInventoryPage<plugins.fossInterfaces.data.IForgeInventoryIssue>> {
+    const scope = this.repositoryScope(scopeArg);
+    return this.page('issues', (item) => this.issue(item, scope), requestArg, scope);
+  }
+
+  /** 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 repositoryScope(scopeArg: TRepositoryScope): TIdentifiedRepositoryScope {
+    const expectedNamespace = this.#options.kind === 'gitea' ? 'gitea.repository.id' : 'gitlab.project.id';
+    if (scopeArg?.kind !== 'repository' || scopeArg.identity?.status !== 'identified' ||
+      scopeArg.identity.ref.instanceId !== this.#options.instanceId || scopeArg.identity.ref.idNamespace !== expectedNamespace ||
+      scopeArg.identity.ref.parentObjectId !== null || typeof scopeArg.identity.ref.objectId !== 'string' ||
+      validation.decimal(scopeArg.identity.ref.objectId) === '0' || !Array.isArray(scopeArg.location?.pathSegments) ||
+      scopeArg.location.pathSegments.length < 2 || (this.#options.kind === 'gitea' && scopeArg.location.pathSegments.length !== 2)) {
+      throw new validation.ForgeInventoryError('invalid-repository-scope');
+    }
+    const pathSegments = scopeArg.location.pathSegments.map((segment) => {
+      if (validation.segments(segment).length !== 1) throw new validation.ForgeInventoryError('invalid-repository-scope');
+      return segment;
+    });
+    return {
+      kind: 'repository', identity: { status: 'identified', ref: {
+        instanceId: this.#options.instanceId, idNamespace: expectedNamespace, objectId: scopeArg.identity.ref.objectId, parentObjectId: null,
+      } },
+      location: { pathSegments, webUrl: validation.httpUrl(scopeArg.location.webUrl) },
+    };
+  }
+
+  private issue(itemArg: unknown, scope: TIdentifiedRepositoryScope): plugins.fossInterfaces.data.IForgeInventoryIssue {
+    const item = validation.record(itemArg);
+    const gitea = this.#options.kind === 'gitea';
+    if (gitea && item.pull_request !== undefined && item.pull_request !== null) throw new validation.ForgeInventoryError('unexpected-pull-request');
+    const repositoryId = validation.decimal(gitea ? validation.record(item.repository).id : item.project_id);
+    if (repositoryId !== scope.identity.ref.objectId) throw new validation.ForgeInventoryError('issue-repository-mismatch');
+    const number = validation.decimal(gitea ? item.number : item.iid);
+    if (number === '0' || typeof item.title !== 'string' || !item.title) throw new validation.ForgeInventoryError('invalid-issue');
+    const body = gitea ? item.body : item.description;
+    if (body !== undefined && body !== null && typeof body !== 'string') throw new validation.ForgeInventoryError('invalid-issue-body');
+    const state = item.state === (gitea ? 'open' : 'opened') ? 'open' : item.state === 'closed' ? 'closed' : null;
+    if (state === null && item.state !== undefined && item.state !== null) throw new validation.ForgeInventoryError('invalid-issue-state');
+    const actor = gitea ? item.user : item.author;
+    let author: plugins.fossInterfaces.data.TForgeInventoryIdentity = { status: 'unresolved', reason: 'Provider author identity was not exposed.' };
+    if (actor !== undefined && actor !== null) {
+      const actorId = validation.record(actor).id;
+      if (gitea && [-1, -2, '-1', '-2'].includes(actorId as number | string)) {
+        author = { status: 'unresolved', reason: 'Gitea reports a deleted or built-in author without a regular user identity.' };
+      } else if (actorId !== undefined && actorId !== null) {
+        author = this.identity(gitea ? 'gitea.user.id' : 'gitlab.user.id', actorId);
+      }
+    }
+    return {
+      identity: this.identity(gitea ? 'gitea.issue.id' : 'gitlab.issue.id', item.id), repository: scope.identity,
+      location: { pathSegments: [...scope.location.pathSegments, ...(gitea ? [] : ['-']), 'issues', number], webUrl: validation.httpUrl(gitea ? item.html_url : item.web_url) },
+      number, title: item.title, body: body ?? null, state,
+      providerType: gitea ? 'issue' : validation.optionalString(item.issue_type),
+      confidential: gitea ? null : validation.optionalBoolean(item.confidential), author,
+      createdAt: validation.timestamp(item.created_at), updatedAt: validation.timestamp(item.updated_at), closedAt: validation.timestamp(item.closed_at),
+    };
+  }
+
   private namespace(itemArg: unknown): plugins.fossInterfaces.data.IForgeInventoryNamespace {
     const item = validation.record(itemArg);
     if (this.#options.kind === 'gitea') {
@@ -115,6 +210,31 @@ export class ForgeInventoryAdapter {
     };
   }
 
+  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') {
@@ -146,9 +266,22 @@ export class ForgeInventoryAdapter {
     };
   }
 
-  private url(state: IContinuation): URL {
+  private url(state: IContinuation, scope?: TIdentifiedRepositoryScope): URL {
     const gitea = this.#options.kind === 'gitea';
-    const endpoint = state.collection === 'repositories' ? (gitea ? 'repos/search' : 'projects') : (gitea ? 'orgs' : 'groups');
+    if (state.collection === 'issues') {
+      if (!scope) throw new validation.ForgeInventoryError('invalid-repository-scope');
+      const endpoint = gitea ? `repos/${scope.location.pathSegments.map(encodeURIComponent).join('/')}/issues`
+        : `projects/${scope.identity.ref.objectId}/issues`;
+      const url = new URL(`${this.#options.baseUrl}/api/${gitea ? 'v1' : 'v4'}/${endpoint}`);
+      url.searchParams.set(gitea ? 'limit' : 'per_page', String(this.#options.pageSize));
+      url.searchParams.set('page', String(state.page)); url.searchParams.set('state', 'all');
+      if (gitea) url.searchParams.set('type', 'issues');
+      else { url.searchParams.set('scope', 'all'); url.searchParams.set('order_by', 'created_at'); url.searchParams.set('sort', 'asc'); }
+      return url;
+    }
+    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) {
@@ -156,6 +289,8 @@ export class ForgeInventoryAdapter {
       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') {
@@ -173,8 +308,9 @@ export class ForgeInventoryAdapter {
     return `${payload}.${plugins.crypto.createHmac('sha256', this.#cursorKey).update(payload).digest('base64url')}`;
   }
 
-  private continuation(collection: TCollection, cursor?: string): IContinuation {
-    if (cursor === undefined) return { version: 1, collection, page: 1, after: null };
+  private continuation(collection: TCollection, cursor?: string, repositoryKey: string | null = null): IContinuation {
+    const directory = collection === 'namespaceDirectory' && this.#options.kind === 'gitea';
+    if (cursor === undefined) return { version: 3, collection, repositoryKey, page: 1, pagesRead: 0, phase: directory ? 'organizations' : null, after: null };
     try {
       if (cursor.length > 2048) throw new Error();
       const [payload, signature, extra] = cursor.split('.');
@@ -182,18 +318,37 @@ export class ForgeInventoryAdapter {
       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 !== 1 || state.collection !== collection || !Number.isSafeInteger(state.page) ||
-        state.page < 2 || state.page > this.#options.maxPages ||
+      if (state.version !== 3 || state.collection !== collection || state.repositoryKey !== repositoryKey || !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) => TItem, requestArg: IForgeInventoryRequest): Promise<plugins.fossInterfaces.data.IForgeInventoryPage<TItem>> {
-    const state = this.continuation(collection, requestArg.cursor);
+  private async page<TItem>(collection: TCollection, map: (value: unknown, state: IContinuation) => TItem, requestArg: IForgeInventoryRequest, scope?: TIdentifiedRepositoryScope): Promise<plugins.fossInterfaces.data.IForgeInventoryPage<TItem>> {
+    const repositoryKey = scope ? plugins.crypto.createHash('sha256').update(JSON.stringify(scope)).digest('hex') : null;
+    const state = this.continuation(collection, requestArg.cursor, repositoryKey);
     const startedAt = new Date().toISOString();
-    const url = this.url(state);
-    const { body, headers } = await this.request(url, requestArg);
+    const url = this.url(state, scope);
+    let pageRequest = requestArg;
+    if (collection === 'issues' && this.#options.kind === 'gitea' && scope) {
+      // Gitea addresses issue lists by mutable path. Check ownership even for empty pages.
+      const before = this.#metrics.responseBytes;
+      const repositoryUrl = new URL(`${this.#options.baseUrl}/api/v1/repos/${scope.location.pathSegments.map(encodeURIComponent).join('/')}`);
+      const probe = await this.request(repositoryUrl, requestArg);
+      if (validation.decimal(validation.record(probe.body).id) !== scope.identity.ref.objectId) {
+        throw new validation.ForgeInventoryError('repository-identity-changed');
+      }
+      if (requestArg.maxResponseBytes !== undefined) {
+        const remaining = requestArg.maxResponseBytes - (this.#metrics.responseBytes - before);
+        if (remaining <= 0) throw new validation.ForgeInventoryError('response-size-limit');
+        pageRequest = { ...requestArg, maxResponseBytes: remaining };
+      }
+    }
+    const { body, headers } = await this.request(url, pageRequest);
     let rows: unknown = body;
     if (this.#options.kind === 'gitea' && collection === 'repositories') {
       const envelope = validation.record(body);
@@ -201,17 +356,17 @@ export class ForgeInventoryAdapter {
       rows = envelope.data;
     }
     if (!Array.isArray(rows) || rows.length > this.#options.pageSize) throw new validation.ForgeInventoryError('invalid-page');
-    const items = rows.map(map);
+    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.page >= this.#options.maxPages
+      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 };
+    return { schemaVersion: 1, instance: this.instance, scope: scope ?? { kind: 'instance' }, observation: this.observation(startedAt), items, pagination };
   }
 
   private next(state: IContinuation, current: URL, headers: Headers, rows: unknown[]): IContinuation | null {
@@ -247,19 +402,20 @@ export class ForgeInventoryAdapter {
     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, after };
+      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 };
+    return { ...state, page: state.page + 1, pagesRead: state.pagesRead + 1 };
   }
 
   private async request(url: URL, requestArg: IForgeInventoryRequest): Promise<{ body: unknown; headers: Headers }> {

package/ts/classes.forgeinventoryscanner.ts

@@ -1,6 +1,6 @@
 import type * as plugins from './plugins.js';
 import { ForgeInventoryAdapter, ForgeInventoryError } from './classes.forgeinventory.js';
-import type { IForgeInventoryMetrics, IForgeInventoryRequest, IForgeInventoryOptions } from './classes.forgeinventory.js';
+import type { IForgeInventoryMetrics, IForgeInventoryRequest, IForgeInventoryOptions, TForgeInventoryVersionInspection } from './classes.forgeinventory.js';
 import { unknownSize } from './forgeinventory.validation.js';
 
 export interface IForgeInventoryScanOptions {
@@ -9,15 +9,28 @@ export interface IForgeInventoryScanOptions {
   maxItems?: number;
   /** Deadline for the complete scan, including body reads. */
   timeoutMs?: number;
-  /** Maximum response bytes consumed across both collections. */
+  /** 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;
+  /** Inspect all visible open/closed issues in the observed repositories. Defaults to false. */
+  includeIssues?: boolean;
 }
 
 export interface IForgeInventoryScan {
   report: plugins.fossInterfaces.data.IForgeInventoryReport;
   repositories: plugins.fossInterfaces.data.IForgeInventoryRepository[];
   namespaces: plugins.fossInterfaces.data.IForgeInventoryNamespace[];
+  issues: plugins.fossInterfaces.data.IForgeInventoryIssue[];
   metrics: IForgeInventoryMetrics;
+  versionInspection: TForgeInventoryVersionInspection | { status: 'notInspected'; reason: string };
+}
+
+interface ICollectedItems<TItem> {
+  items: TItem[];
+  result: plugins.fossInterfaces.data.TForgeInventoryCollectionResult;
 }
 
 const entityClasses = {
@@ -48,27 +61,53 @@ export class ForgeInventoryScanner {
       !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') ||
+      (optionsArg.includeIssues !== undefined && typeof optionsArg.includeIssues !== 'boolean')) {
+      throw new ForgeInventoryError('invalid-scan-options');
+    }
+    const { signal } = optionsArg;
+    const inspectVersion = optionsArg.inspectVersion ?? false;
+    const namespaceDirectory = optionsArg.namespaceDirectory ?? false;
+    const includeIssues = optionsArg.includeIssues ?? false;
     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 });
+    if (signal?.aborted) controller.abort();
+    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 organization/group scan.' },
+      result: { status: 'notInspected', reason: 'No inventory reader has inspected this entity class in this scan.' },
     }])) as plugins.fossInterfaces.data.IForgeInventoryReport['collections'];
     try {
-      const namespaces = await this.collect((request) => this.#adapter.listNamespaces(request), maxItems, controller.signal, deadline, remainingBytes);
+      if (Date.now() >= deadline) controller.abort();
+      const versionInspection: IForgeInventoryScan['versionInspection'] = 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) => 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 issues = includeIssues
+        ? await this.collectIssues(repositories, maxItems, controller.signal, deadline, remainingBytes) : null;
+      if (issues) collections.issues = {
+        capability: repositories.items.length === 0
+          ? { status: 'unverified', reason: 'No repository issue endpoint was inspected.' }
+          : this.capability(issues, ['Only API-visible issue metadata is enumerated.', 'Comments, associations, attachments and historical import fidelity are not established.']),
+        result: issues.result,
+      };
       const namespaceLimitation = 'Only organization/group namespaces were inspected; personal namespaces and full private namespace coverage remain uninspected.';
       collections.namespaces = {
-        capability: this.capability(namespaces, [namespaceLimitation, 'Live API visibility does not prove administrator completeness.']),
-        result: namespaces.result.status === 'enumerated' ? {
+        capability: this.capability(namespaces, [
+          ...(namespaceDirectory ? [] : [namespaceLimitation]),
+          'Live API visibility does not prove administrator completeness.',
+          'Namespace metadata does not establish user identity or permission inventory.',
+        ]),
+        result: !namespaceDirectory && namespaces.result.status === 'enumerated' ? {
           status: 'incomplete', observation: namespaces.result.observation,
           observedCount: namespaces.result.count, reason: namespaceLimitation,
         } : namespaces.result,
@@ -87,14 +126,16 @@ export class ForgeInventoryScanner {
       const after = this.#adapter.metrics;
       return {
         report: {
-          schemaVersion: 1, instance: this.#adapter.instance, scope: { kind: 'instance' }, collections,
-          additionalCollections: [{
+          schemaVersion: 1,
+          instance: { ...this.#adapter.instance, version: versionInspection.status === 'observed' ? versionInspection.version : null },
+          scope: { kind: 'instance' }, collections,
+          additionalCollections: 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,
+        repositories: repositories.items, namespaces: namespaces.items, issues: issues?.items ?? [], versionInspection,
         metrics: {
           requests: after.requests - before.requests,
           responseBytes: after.responseBytes - before.responseBytes,
@@ -102,7 +143,7 @@ export class ForgeInventoryScanner {
         },
       };
     } finally {
-      controller.abort(); clearTimeout(timeout); optionsArg.signal?.removeEventListener('abort', abort);
+      controller.abort(); clearTimeout(timeout); signal?.removeEventListener('abort', abort);
       this.#running = false;
     }
   }
@@ -118,10 +159,10 @@ export class ForgeInventoryScanner {
   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 }> {
+    identities = new Set<string>(),
+  ): Promise<ICollectedItems<TItem>> {
     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,
@@ -149,4 +190,30 @@ export class ForgeInventoryScanner {
       cursor = page.pagination.cursor;
     }
   }
+
+  private async collectIssues(
+    repositories: ICollectedItems<plugins.fossInterfaces.data.IForgeInventoryRepository>,
+    maxItems: number, signal: AbortSignal, deadline: number, remainingBytes: () => number,
+  ): Promise<ICollectedItems<plugins.fossInterfaces.data.IForgeInventoryIssue>> {
+    const startedAt = new Date().toISOString();
+    const items: plugins.fossInterfaces.data.IForgeInventoryIssue[] = [];
+    const identities = new Set<string>();
+    const incomplete = (reason: string): ICollectedItems<plugins.fossInterfaces.data.IForgeInventoryIssue> => ({
+      items, result: { status: 'incomplete', observation: this.#adapter.observation(startedAt), observedCount: String(items.length), reason },
+    });
+    for (const repository of repositories.items) {
+      const collection = await this.collect((request) => this.#adapter.listIssues({
+        kind: 'repository', identity: repository.identity, location: repository.location,
+      }, request), maxItems - items.length, signal, deadline, remainingBytes, identities);
+      for (const item of collection.items) items.push(item);
+      if (collection.result.status !== 'enumerated') {
+        return incomplete('reason' in collection.result ? collection.result.reason : 'Repository issue scan did not complete.');
+      }
+    }
+    if (signal.aborted || Date.now() >= deadline) return incomplete('Scan aborted or deadline reached.');
+    if (repositories.result.status !== 'enumerated') return incomplete('The repository inventory was incomplete.');
+    return {
+      items, result: { status: 'enumerated', observation: this.#adapter.observation(startedAt), count: String(items.length), sizeBytes: unknownSize('Issue storage bytes were not measured.') },
+    };
+  }
 }

package/ts/forgeinventory.validation.ts

@@ -37,6 +37,19 @@ export const optionalBoolean = (value: unknown): boolean | null => {
   return value;
 };
 
+/** Keep provider timestamp precision and offset; reject invalid calendar dates. */
+export const timestamp = (value: unknown): string | null => {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== 'string') throw new ForgeInventoryError('invalid-timestamp');
+  const match = value.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/);
+  if (!match || !Number.isFinite(Date.parse(value)) || Number(match[2]) < 1 || Number(match[2]) > 12 ||
+    Number(match[3]) < 1 || Number(match[3]) > new Date(Date.UTC(Number(match[1]), Number(match[2]), 0)).getUTCDate() ||
+    Number(match[4]) > 23 || Number(match[5]) > 59 || Number(match[6]) > 59) {
+    throw new ForgeInventoryError('invalid-timestamp');
+  }
+  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))) {