zopia 0.3.0

package/src/validation.ts

@@ -0,0 +1,299 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { lstat, readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { asZopiaError, ZopiaError, type ZopiaErrorCode } from './errors';
+import type { ZopiaWarningCode } from './warnings';
+import { normalizeOpenApiDocument, type OpenApiDocument } from './conversions/openapi';
+import { bundleExternalOpenApiRefs } from './conversions/openapi-external-ref';
+import { readOpenApiSourceInput, validateOpenApiReferences } from './conversions/openapi-to-api-docs-public';
+import { collectOpenApiOperations, collectOpenApiWebhookOperations } from './conversions/openapi-to-api-docs';
+import { assertUniqueOperationIdsAcrossScopes, planApiDocsFiles, planWebhookDocsFiles } from './conversions/api-docs-plan';
+import { apiDocsToOpenApi } from './conversions/manifest-to-openapi';
+import { validateZopiaManifest, ZOPIA_MANIFEST_FILE, type ZopiaManifest } from './conversions/manifest-writer';
+
+/** Stable lint codes emitted only by the validator ({@link validateZopia}). */
+export const ZOPIA_VALIDATION_CODES = Object.freeze([
+  'ZOPIA_VALIDATE_UNREACHABLE_COMPONENT',
+  'ZOPIA_VALIDATE_KM_API_DRIFT',
+] as const);
+
+/** Stable, machine-readable validator lint code. */
+export type ZopiaValidationCode = typeof ZOPIA_VALIDATION_CODES[number];
+
+/** One deterministic validator finding, either a hard failure or a lint observation. */
+export interface ZopiaValidationIssue {
+  /** Whether the finding blocks validity (`error`) or is advisory (`warning`). */
+  severity: 'error' | 'warning';
+  /** Stable code: a validator lint code, or the caught engine {@link ZopiaErrorCode} / warning code. */
+  code: ZopiaValidationCode | ZopiaErrorCode | ZopiaWarningCode;
+  /** JSON Pointer or file location associated with the finding, when known. */
+  at?: string;
+  /** Human-readable finding description. */
+  message: string;
+}
+
+/** Deterministic validator outcome for one target. */
+export interface ZopiaValidationResult {
+  /** Whether no error-severity issues were found. */
+  ok: boolean;
+  /** How the validator classified the target. */
+  kind: 'spec' | 'docs';
+  /** The input as the validator understood it (path, or a placeholder for inline text/objects). */
+  target: string;
+  /** Findings sorted by severity (errors first), pointer, code, and message. */
+  diagnostics: ZopiaValidationIssue[];
+}
+
+/** Options for {@link validateZopia}. */
+export interface ZopiaValidateOptions {
+  /**
+   * Force target classification instead of auto-detecting from the input.
+   *
+   * @default 'auto'
+   */
+  kind?: 'spec' | 'docs' | 'auto';
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+function sortDiagnostics(issues: ZopiaValidationIssue[]): ZopiaValidationIssue[] {
+  return [...issues].sort((left, right) => {
+    const key = (issue: ZopiaValidationIssue): string => [issue.severity === 'error' ? '0' : '1', issue.at ?? '', issue.code, issue.message].join('\u0000');
+    const a = key(left);
+    const b = key(right);
+    return a < b ? -1 : a > b ? 1 : 0;
+  });
+}
+
+function issueError(error: unknown): ZopiaValidationIssue {
+  const typed = error instanceof ZopiaError ? error : asZopiaError(error, 'ZOPIA_SPEC_INVALID', 'validation failure');
+  return { severity: 'error', code: typed.code, ...(typed.at === undefined ? {} : { at: typed.at }), message: typed.message.slice(`${typed.code}: `.length) };
+}
+
+/** One `#/components/schemas/…`/`#/definitions/…` reference plus whether it can seed reachability. */
+interface SchemaRefOccurrence {
+  /** Referenced component name with `~`-escapes unescaped. */
+  name: string;
+  /** Whether the occurrence lives outside the schema map itself and may act as a reachability root. */
+  root: boolean;
+}
+
+const decodePointerSegment = (segment: string): string => segment.replace(/~1/g, '/').replace(/~0/g, '~');
+
+function walkSchemaRefs(value: unknown, inSchemaMap: boolean, inExample: boolean, stack: Set<object>, out: SchemaRefOccurrence[], pattern: RegExp, schemaKey: string): void {
+  if (!value || typeof value !== 'object' || stack.has(value as object)) return;
+  stack.add(value as object);
+  try {
+    if (Array.isArray(value)) {
+      for (const child of value) walkSchemaRefs(child, inSchemaMap, inExample, stack, out, pattern, schemaKey);
+      return;
+    }
+    const object = value as Record<string, unknown>;
+    // Track the path (not the whole graph) so a subtree shared between an example and
+    // a schema position in an in-memory document still reports the schema occurrence.
+    if (!inExample && typeof object.$ref === 'string') {
+      const match = pattern.exec(object.$ref);
+      if (match) out.push({ name: decodePointerSegment(match[1]), root: !inSchemaMap });
+    }
+    for (const [key, child] of Object.entries(object)) {
+      const childInSchemaMap = inSchemaMap || key === schemaKey;
+      const childInExample = inExample || key === 'example' || key === 'examples';
+      walkSchemaRefs(child, childInSchemaMap, childInExample, stack, out, pattern, schemaKey);
+    }
+  } finally {
+    stack.delete(value as object);
+  }
+}
+
+/**
+ * List components never reachable from any operation-side `$ref` (transitively).
+ * Examples do not seed reachability; schemas reachable only through other
+ * unreachable schemas stay unreachable.
+ */
+function lintUnreachableComponents(document: OpenApiDocument, version: string): ZopiaValidationIssue[] {
+  const isSwagger = version === '2.0';
+  const mapPointer = isSwagger ? '/definitions' : '/components/schemas';
+  const schemas = isSwagger
+    ? document.definitions
+    : isRecord(document.components) ? document.components.schemas : undefined;
+  if (!isRecord(schemas)) return [];
+  const pattern = isSwagger ? /^#\/definitions\/([^/]+)$/ : /^#\/components\/schemas\/([^/]+)$/;
+  const schemaKey = isSwagger ? 'definitions' : 'schemas';
+  const occurrences: SchemaRefOccurrence[] = [];
+  walkSchemaRefs(document, false, false, new Set(), occurrences, pattern, schemaKey);
+  const reached = new Set<string>();
+  const queue = occurrences.filter((occurrence) => occurrence.root).map((occurrence) => occurrence.name);
+  while (queue.length) {
+    const name = queue.pop()!;
+    if (reached.has(name)) continue;
+    reached.add(name);
+    const schema = schemas[name];
+    if (schema === undefined) continue;
+    const nested: SchemaRefOccurrence[] = [];
+    walkSchemaRefs(schema, true, false, new Set(), nested, pattern, schemaKey);
+    for (const occurrence of nested) queue.push(occurrence.name);
+  }
+  return Object.keys(schemas)
+    .filter((name) => !reached.has(name) && name !== '')
+    .map((name) => ({
+      severity: 'warning' as const,
+      code: 'ZOPIA_VALIDATE_UNREACHABLE_COMPONENT' as const,
+      at: `#${mapPointer}/${name.replace(/~/g, '~0').replace(/\//g, '~1')}`,
+      message: `component is never referenced: ${name}`,
+    }));
+}
+
+const KMAPI_DRIFT = 'ZOPIA_VALIDATE_KM_API_DRIFT' as const;
+
+/** Read the km-api peer range zopia was built with. */
+function zopiaKmApiPeerRange(): string | undefined {
+  try {
+    const text = readFileSync(new URL('../package.json', import.meta.url), 'utf8');
+    const peer = (JSON.parse(text) as { peerDependencies?: Record<string, unknown> }).peerDependencies?.['km-api'];
+    return typeof peer === 'string' ? peer : undefined;
+  } catch { return undefined; }
+}
+
+/** Resolve the installed km-api version visible from the validated tree (no exports-map dependence). */
+function installedKmApiVersion(treeRoot: string): string | undefined {
+  let directory = resolve(treeRoot);
+  for (;;) {
+    try {
+      const candidate = join(directory, 'node_modules', 'km-api', 'package.json');
+      const version = (JSON.parse(readFileSync(candidate, 'utf8')) as { version?: unknown }).version;
+      if (typeof version === 'string') return version;
+    } catch { /* keep walking upward */ }
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+/** Minimal caret-range check (`^x.y.z`), matching the form zopia declares. */
+function satisfiesCaretRange(version: string, range: string): boolean {
+  const base = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.replace(/^[^0-9]*/, ''));
+  const wanted = /^\^0*(\d+)(?:\.0*(\d+))?(?:\.0*(\d+))?/.exec(range.trim());
+  if (!base || !wanted) return true; // unparsable: never accuse drift on data we cannot read
+  const [major, minor, patch] = [Number(base[1]), Number(base[2]), Number(base[3])];
+  const [baseMajor, baseMinor, basePatch] = [Number(wanted[1]), Number(wanted[2] ?? 0), Number(wanted[3] ?? 0)];
+  if (baseMajor > 0) return major === baseMajor && (minor > baseMinor || (minor === baseMinor && patch >= basePatch));
+  return major === 0 && minor === baseMinor && patch >= basePatch;
+}
+
+function kmApiDriftDiagnostics(treeRoot: string): ZopiaValidationIssue[] {
+  const range = zopiaKmApiPeerRange();
+  if (range === undefined) return [];
+  const version = installedKmApiVersion(treeRoot);
+  if (version === undefined) {
+    return [{ severity: 'warning', code: KMAPI_DRIFT, at: treeRoot, message: `km-api could not be resolved near the generated tree; generated modules require peer ${range}` }];
+  }
+  if (!satisfiesCaretRange(version, range)) {
+    return [{ severity: 'warning', code: KMAPI_DRIFT, at: treeRoot, message: `installed km-api ${version} is outside the required peer range ${range}` }];
+  }
+  return [];
+}
+
+async function validateDocsTarget(path: string): Promise<ZopiaValidationResult> {
+  const issues: ZopiaValidationIssue[] = [];
+  const stats = existsSync(path) ? await lstat(path) : undefined;
+  const manifestFile = stats?.isDirectory() === true ? join(path, ZOPIA_MANIFEST_FILE) : path;
+  const treeRoot = stats?.isDirectory() === true ? path : dirname(path);
+  let manifest: ZopiaManifest | undefined;
+  if (!existsSync(manifestFile)) {
+    issues.push({ severity: 'error', code: 'ZOPIA_DOCS_MISSING_MANIFEST', at: manifestFile, message: 'manifest file not found; generate api docs first or pass the manifest path' });
+  } else {
+    try {
+      const parsed = JSON.parse(await readFile(manifestFile, 'utf8')) as ZopiaManifest;
+      validateZopiaManifest(parsed);
+      manifest = parsed;
+    } catch (error) {
+      issues.push(issueError(error));
+    }
+  }
+  if (manifest !== undefined) {
+    try {
+      const reversed = await apiDocsToOpenApi(manifestFile);
+      for (const warning of reversed.warnings) issues.push({ severity: 'warning', code: warning.code, ...(warning.at === undefined ? {} : { at: warning.at }), message: warning.message });
+    } catch (error) {
+      issues.push(issueError(error));
+    }
+    issues.push(...kmApiDriftDiagnostics(treeRoot));
+  }
+  const diagnostics = sortDiagnostics(issues);
+  return { ok: !diagnostics.some((issue) => issue.severity === 'error'), kind: 'docs', target: path, diagnostics };
+}
+
+async function validateSpecTarget(input: string | Record<string, unknown>, target: string): Promise<ZopiaValidationResult> {
+  const issues: ZopiaValidationIssue[] = [];
+  let document: OpenApiDocument;
+  try {
+    let read = await readOpenApiSourceInput(input);
+    const bundled = read.sourceFile ? await bundleExternalOpenApiRefs(read.document, read.sourceFile) : read.document;
+    document = normalizeOpenApiDocument(bundled).document;
+  } catch (error) {
+    issues.push(issueError(error));
+    const diagnostics = sortDiagnostics(issues);
+    return { ok: false, kind: 'spec', target, diagnostics };
+  }
+  try { validateOpenApiReferences(document); }
+  catch (error) {
+    issues.push(issueError(error));
+    const diagnostics = sortDiagnostics(issues);
+    return { ok: false, kind: 'spec', target, diagnostics };
+  }
+  const collectorsOk = { paths: false, webhooks: false };
+  try { collectOpenApiOperations(document); collectorsOk.paths = true; }
+  catch (error) { issues.push(issueError(error)); }
+  try { collectOpenApiWebhookOperations(document); collectorsOk.webhooks = true; }
+  catch (error) { issues.push(issueError(error)); }
+  if (collectorsOk.paths) {
+    try {
+      const plans = planApiDocsFiles(document);
+      if (collectorsOk.webhooks) {
+        try { assertUniqueOperationIdsAcrossScopes(plans, planWebhookDocsFiles(document)); }
+        catch (error) { issues.push(issueError(error)); }
+      }
+    } catch (error) { issues.push(issueError(error)); }
+  }
+  if (collectorsOk.paths) issues.push(...lintUnreachableComponents(document, document.openapi ?? document.swagger ?? '3.1'));
+  const diagnostics = sortDiagnostics(issues);
+  return { ok: !diagnostics.some((issue) => issue.severity === 'error'), kind: 'spec', target, diagnostics };
+}
+
+/**
+ * Lint or validate a Swagger/OpenAPI spec or a generated api-docs tree (Phase 3).
+ *
+ * Specs are checked for dialect validity, broken local references, endpoint
+ * planning failures (name collisions, cross-namespace duplicate operationIds),
+ * and components no operation can reach. Generated trees are checked for a
+ * readable manifest, a successful reverse dry-run, and km-api peer drift.
+ * Unlike the engines, validation never fails fast: every detectable problem is
+ * reported as a deterministic diagnostic and the result only signals validity
+ * through `ok`.
+ *
+ * @param input Spec object/text/path, generated docs directory, or manifest file path.
+ * @param options Optional target classification override.
+ * @returns Validation outcome with sorted diagnostics; `ok` ignores warning-severity findings.
+ * @throws {@link ZopiaError} `ZOPIA_CONFIG_INVALID` when the input or options are unusable.
+ * @example
+ * ```ts
+ * import { validateZopia } from 'zopia';
+ *
+ * const result = await validateZopia('openapi.yaml');
+ * for (const issue of result.diagnostics) console.error(issue.code, issue.at, issue.message);
+ * ```
+ */
+export async function validateZopia(input: string | Record<string, unknown>, options: ZopiaValidateOptions = {}): Promise<ZopiaValidationResult> {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) throw new ZopiaError('ZOPIA_CONFIG_INVALID', 'validate options must be an object', { at: 'options' });
+  const kind = options.kind ?? 'auto';
+  if (kind !== 'spec' && kind !== 'docs' && kind !== 'auto') throw new ZopiaError('ZOPIA_CONFIG_INVALID', `invalid validate kind: ${String(kind)}`, { at: 'kind', hint: "use 'spec', 'docs', or 'auto'" });
+  const resolvedKind = kind === 'auto'
+    ? (typeof input === 'string' && ((existsSync(input) && (await lstat(input)).isDirectory()) || /(?:^|\/)\.zopia-manifest\.json$/i.test(input)) ? 'docs' : 'spec' as const)
+    : kind;
+  if (resolvedKind === 'docs') {
+    if (typeof input !== 'string' || input.trim() === '') throw new ZopiaError('ZOPIA_CONFIG_INVALID', 'docs validation requires a docs directory or manifest path', { at: 'input', hint: 'pass the generated api-docs directory or its .zopia-manifest.json' });
+    return validateDocsTarget(input);
+  }
+  const target = typeof input === 'string' ? (input.trimStart().startsWith('{') || input.includes('\n:') ? '(inline document)' : input) : '(in-memory document)';
+  return validateSpecTarget(input, target);
+}

package/src/warnings.ts

@@ -0,0 +1,164 @@
+import { asZopiaError, ZopiaError } from './errors';
+
+/** Stable warning codes emitted by zopia's conversion pipelines. */
+export const ZOPIA_WARNING_CODES = [
+  'ZOPIA_WARN_CONTENT_ENCODING',
+  'ZOPIA_WARN_CUSTOM_FORMAT',
+  'ZOPIA_WARN_DEFAULT_INFO',
+  'ZOPIA_WARN_DEFAULT_SECURITY',
+  'ZOPIA_WARN_DIALECT_DOWNGRADE',
+  'ZOPIA_WARN_FROZEN_SUBTREE',
+  'ZOPIA_WARN_INT64',
+  'ZOPIA_WARN_INVALID_SCHEMA',
+  'ZOPIA_WARN_LEGACY_EXCLUSIVE_BOUND',
+  'ZOPIA_WARN_MULTI_CONTENT',
+  'ZOPIA_WARN_NOT',
+  'ZOPIA_WARN_ONE_OF',
+  'ZOPIA_WARN_PRESET_PRIMARY_TAG',
+  'ZOPIA_WARN_REF',
+  'ZOPIA_WARN_SERVER_VARIABLES',
+  'ZOPIA_WARN_STALE_TREE',
+  'ZOPIA_WARN_UNIQUE_ITEMS',
+  'ZOPIA_WARN_UNREPRESENTABLE',
+  'ZOPIA_WARN_WEBHOOKS',
+] as const;
+
+/** Stable, machine-readable warning code. */
+export type ZopiaWarningCode = typeof ZOPIA_WARNING_CODES[number];
+
+/** A non-fatal, structured diagnostic produced by a lossy conversion. */
+export interface ZopiaWarning {
+  /** Stable, machine-readable warning code. */
+  code: ZopiaWarningCode;
+  /** JSON Pointer identifying the affected source or output location, when available. */
+  at?: string;
+  /** Human-readable description of the approximation or loss. */
+  message: string;
+}
+
+const cleanText = (value: string): string => value.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, ' ').trim();
+const displayLocation = (value: string): string => value.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+const warningKey = (warning: ZopiaWarning): string => JSON.stringify([warning.at ?? null, warning.code, warning.message]);
+
+function normalizeWarning(warning: ZopiaWarning): ZopiaWarning {
+  if (!warning || typeof warning !== 'object' || Array.isArray(warning)) throw new ZopiaError('ZOPIA_WARNING_INVALID', 'warning must be an object', { at: 'warning' });
+  if (!ZOPIA_WARNING_CODES.includes(warning.code)) throw new ZopiaError('ZOPIA_WARNING_INVALID', `Unknown zopia warning code: ${String(warning.code)}`, { at: 'code', hint: 'use a code from ZOPIA_WARNING_CODES' });
+  if (warning.at !== undefined && (typeof warning.at !== 'string' || warning.at.length === 0)) throw new ZopiaError('ZOPIA_WARNING_INVALID', 'warning location must be a non-empty string', { at: 'at', hint: 'omit the location or provide a JSON Pointer' });
+  if (typeof warning.message !== 'string' || cleanText(warning.message).length === 0) throw new ZopiaError('ZOPIA_WARNING_INVALID', 'warning message must be a non-empty string', { at: 'message', hint: 'provide a concise warning description' });
+  return { code: warning.code, ...(warning.at === undefined ? {} : { at: warning.at }), message: cleanText(warning.message) };
+}
+
+/**
+ * Return detached, deduplicated warnings in deterministic location/code/message order.
+ *
+ * @param warnings Structured warnings to validate, normalize, and sort.
+ * @returns A detached deterministic array with exact duplicates removed.
+ * @throws {@link ZopiaError} when a warning or the iterable is invalid.
+ */
+export function normalizeZopiaWarnings(warnings: Iterable<ZopiaWarning>): ZopiaWarning[] {
+  try {
+    if (warnings === null || warnings === undefined || typeof (warnings as { [Symbol.iterator]?: unknown })[Symbol.iterator] !== 'function') throw new ZopiaError('ZOPIA_WARNING_INVALID', 'warnings must be iterable', { at: 'warnings' });
+    const unique = new Map<string, ZopiaWarning>();
+    for (const input of warnings) {
+      const warning = normalizeWarning(input);
+      unique.set(warningKey(warning), warning);
+    }
+    return [...unique.values()].sort((left, right) => {
+      const a = warningKey(left); const b = warningKey(right);
+      return a < b ? -1 : a > b ? 1 : 0;
+    });
+  } catch (error) {
+    throw asZopiaError(error, 'ZOPIA_WARNING_INVALID', 'unable to normalize warnings', { at: 'warnings' });
+  }
+}
+
+/**
+ * Prefix a warning's JSON Pointer with a containing source location.
+ *
+ * @param warning Structured warning to validate and relocate.
+ * @param base Containing JSON Pointer beginning with `#`.
+ * @returns A normalized warning beneath `base`.
+ * @throws {@link ZopiaError} when the warning or base pointer is invalid.
+ */
+export function rebaseZopiaWarning(warning: ZopiaWarning, base: string): ZopiaWarning {
+  if (typeof base !== 'string' || !base.startsWith('#')) throw new ZopiaError('ZOPIA_WARNING_INVALID', `invalid warning base pointer: ${base}`, { at: 'base', hint: "use a JSON Pointer beginning with '#'" });
+  const value = normalizeWarning(warning);
+  const suffix = value.at === undefined || value.at === '#' ? '' : value.at.startsWith('#/') ? value.at.slice(1) : value.at;
+  return normalizeWarning({ ...value, at: `${base}${suffix}` });
+}
+
+/**
+ * Format a warning for stderr or logs without multiline injection.
+ *
+ * @param warning Structured warning to validate and format.
+ * @returns A stable single-line diagnostic.
+ * @throws {@link ZopiaError} when the warning is invalid.
+ */
+export function formatZopiaWarning(warning: ZopiaWarning): string {
+  const value = normalizeWarning(warning);
+  return `${value.code}${value.at ? ` ${displayLocation(value.at)}` : ''}: ${value.message}`;
+}
+
+/**
+ * Format the canonical generated-code marker required by D-12.
+ *
+ * @param warning Structured warning to validate and format.
+ * @param subject Generated-code subject associated with the warning.
+ * @returns A stable single-line `@zopia:warn` source comment.
+ * @throws {@link ZopiaError} when the warning or subject is invalid.
+ */
+export function formatZopiaWarningComment(warning: ZopiaWarning, subject: string): string {
+  const value = normalizeWarning(warning);
+  if (typeof subject !== 'string') throw new ZopiaError('ZOPIA_WARNING_INVALID', 'warning subject must be a string', { at: 'subject' });
+  const label = cleanText(subject) || 'schema';
+  return `// @zopia:warn ${value.code} ${label} — ${value.message}${value.at ? ` (${displayLocation(value.at)})` : ''}`;
+}
+
+/** Deterministic warning accumulator shared by public engine wrappers. */
+export class ZopiaWarningCollector {
+  readonly #warnings = new Map<string, ZopiaWarning>();
+
+  /**
+   * Add one warning after validating and normalizing it.
+   *
+   * @param input Structured warning to add.
+   * @returns Nothing.
+   * @throws {@link ZopiaError} when the warning is invalid.
+   */
+  add(input: ZopiaWarning): void {
+    const warning = normalizeWarning(input);
+    this.#warnings.set(warningKey(warning), warning);
+  }
+
+  /**
+   * Add all warnings from an iterable.
+   *
+   * @param inputs Structured warnings to normalize and add.
+   * @returns Nothing.
+   * @throws {@link ZopiaError} when the iterable or any warning is invalid.
+   */
+  addAll(inputs: Iterable<ZopiaWarning>): void {
+    for (const warning of normalizeZopiaWarnings(inputs)) this.add(warning);
+  }
+
+  /**
+   * Add warnings rebased beneath one containing JSON Pointer.
+   *
+   * @param inputs Structured warnings to normalize and add.
+   * @param base Containing JSON Pointer beginning with `#`.
+   * @returns Nothing.
+   * @throws {@link ZopiaError} when the iterable, warning, or base pointer is invalid.
+   */
+  addRebased(inputs: Iterable<ZopiaWarning>, base: string): void {
+    for (const warning of normalizeZopiaWarnings(inputs)) this.add(rebaseZopiaWarning(warning, base));
+  }
+
+  /**
+   * Return a detached, deduplicated, deterministically sorted snapshot.
+   *
+   * @returns Current normalized warnings in stable order.
+   */
+  toArray(): ZopiaWarning[] {
+    return normalizeZopiaWarnings(this.#warnings.values());
+  }
+}