@vrtmrz/livesync-commonlib 0.1.41 → 0.1.43

package/dist/diagnostics/local.js

@@ -0,0 +1,25 @@
+function createLocalDiagnosticSource(database) {
+  return {
+    info: () => database.info(),
+    get: (id, options) => database.get(id, options),
+    async *enumerateIds() {
+      let previous;
+      while (true) {
+        const page = await database.allDocs({
+          limit: 256,
+          ...previous === void 0 ? {} : { startkey: previous, skip: 1 }
+        });
+        for (const row of page.rows) {
+          if (!row.value.deleted) yield row.id;
+        }
+        if (page.rows.length < 256) return;
+        const last = page.rows.at(-1).id;
+        if (last === previous) throw new Error("Document enumeration did not advance");
+        previous = last;
+      }
+    }
+  };
+}
+export {
+  createLocalDiagnosticSource
+};

package/dist/diagnostics/reports.d.ts

@@ -0,0 +1,108 @@
+import type { DatabaseIntegrityResult, DiagnosticCoverage, DiagnosticError, DiagnosticIdentitySettings, DiagnosticNameMode, DiagnosticObservation, DiagnosticSourceName, DiagnosticStatus } from "./types.js";
+import type { DatabaseUsageError, DatabaseUsageResult, DatabaseUsageStatus } from "./usage.js";
+export interface DiagnosticNameMapper {
+    readonly mode: DiagnosticNameMode;
+    path(value: string): string;
+    id(value: string): string;
+    revision(value: string): string;
+    chunk(value: string): string;
+}
+export interface DiagnosticReportVersions {
+    commonlib?: string;
+    plugin?: string;
+    application?: string;
+}
+/** Creates run-local name aliases. Each name domain has an independent map. */
+export declare function createDiagnosticNameMapper(mode: DiagnosticNameMode): DiagnosticNameMapper;
+export interface ProjectedDiagnosticError {
+    source: DiagnosticError["source"];
+    reason: DiagnosticError["reason"];
+    id?: string;
+    revision?: string;
+    path?: string;
+    chunkId?: string;
+}
+export interface ProjectedDiagnosticObservation {
+    reference: string;
+    source: DiagnosticSourceName;
+    id: string;
+    revision?: string;
+    path: string;
+    expectedId?: string;
+    identity: DiagnosticObservation["identity"];
+    logicallyDeleted: boolean;
+    branch: DiagnosticObservation["branch"];
+    conflictCount: number;
+    pathIsNFC: boolean;
+    caseEquivalentPaths: boolean;
+    nfcEquivalentPaths: boolean;
+    otherSourceGroup: DiagnosticObservation["otherSourceGroup"];
+    vault: {
+        reference: string;
+        status: DiagnosticObservation["vault"]["status"];
+        reason?: DiagnosticObservation["vault"]["reason"];
+    };
+    content: {
+        status: DiagnosticObservation["content"]["status"];
+        reason?: DiagnosticObservation["content"]["reason"];
+        chunksRead: number;
+        unavailableChunks: {
+            id: string;
+            status: "missing" | "unreadable";
+        }[];
+    };
+    comparisons: {
+        against: string;
+        relation: DiagnosticObservation["comparisons"][number]["relation"];
+    }[];
+}
+export interface ProjectedDatabaseIntegrityReport {
+    schemaVersion: 1;
+    kind: "integrity";
+    status: DiagnosticStatus;
+    nameMode: DiagnosticNameMode;
+    versions: DiagnosticReportVersions;
+    settings: DiagnosticIdentitySettings;
+    coverage: Record<DiagnosticSourceName, DiagnosticCoverage>;
+    observations: ProjectedDiagnosticObservation[];
+    errors: ProjectedDiagnosticError[];
+    scope: DatabaseIntegrityResult["scope"];
+}
+export interface ProjectedDatabaseUsageRow {
+    title: string;
+    id: string;
+    path: string;
+    revision: string;
+    rev: string;
+    revHash: string;
+    uniqueChunkCount: number;
+    sharedChunkCount: number;
+    uniqueChunkSize: number;
+    sharedChunkSize: number;
+}
+export interface ProjectedDatabaseUsageError {
+    code: DatabaseUsageError["code"];
+    id?: string;
+    revision?: string;
+}
+export interface ProjectedDatabaseUsageReport {
+    version: 1;
+    kind: "usage";
+    status: DatabaseUsageStatus;
+    nameMode: DiagnosticNameMode;
+    versions: DiagnosticReportVersions;
+    changedDuringRun?: boolean;
+    rows: ProjectedDatabaseUsageRow[];
+    errors: ProjectedDatabaseUsageError[];
+}
+export type ProjectedDiagnosticReport = ProjectedDatabaseIntegrityReport | ProjectedDatabaseUsageReport;
+/** Copies only the documented report fields and projects every stored name through the run mapper. */
+export declare function projectIntegrityReport(result: DatabaseIntegrityResult, mapper: DiagnosticNameMapper, versions?: DiagnosticReportVersions): ProjectedDatabaseIntegrityReport;
+/** Projects Usage rows and errors without carrying through extra analyser fields. */
+export declare function projectUsageReport(result: DatabaseUsageResult, mapper: DiagnosticNameMapper, versions?: DiagnosticReportVersions): ProjectedDatabaseUsageReport;
+/** Formats the legacy nine-column Usage export from an already projected report. */
+export declare function formatUsageTSV(projected: ProjectedDatabaseUsageReport): string;
+/** Serialises a projected report. Raw analyser values never enter this formatter. */
+export declare function formatDiagnosticJSON(projected: ProjectedDiagnosticReport): string;
+/** Renders the same projected integrity fields used by JSON, with user-controlled values in escaped code spans. */
+export declare function formatIntegrityMarkdown(projected: ProjectedDatabaseIntegrityReport): string;

package/dist/diagnostics/reports.js

@@ -0,0 +1,353 @@
+function createDomainMapper(prefix) {
+  const aliases = /* @__PURE__ */ new Map();
+  return (value) => {
+    const existing = aliases.get(value);
+    if (existing !== void 0) return existing;
+    const alias = `${prefix}-${String(aliases.size + 1).padStart(3, "0")}`;
+    aliases.set(value, alias);
+    return alias;
+  };
+}
+function createDiagnosticNameMapper(mode) {
+  if (mode === "original") {
+    const original = (value) => value;
+    return { mode, path: original, id: original, revision: original, chunk: original };
+  }
+  return {
+    mode,
+    path: createDomainMapper("file"),
+    id: createDomainMapper("document"),
+    revision: createDomainMapper("revision"),
+    chunk: createDomainMapper("chunk")
+  };
+}
+function copyVersions(versions) {
+  return {
+    ...versions.commonlib === void 0 ? {} : { commonlib: versions.commonlib },
+    ...versions.plugin === void 0 ? {} : { plugin: versions.plugin },
+    ...versions.application === void 0 ? {} : { application: versions.application }
+  };
+}
+function copyCoverage(coverage) {
+  return {
+    status: coverage.status,
+    documents: coverage.documents,
+    metadata: coverage.metadata,
+    excluded: coverage.excluded,
+    conflictBranches: coverage.conflictBranches,
+    contentReads: coverage.contentReads,
+    changedDuringRun: coverage.changedDuringRun
+  };
+}
+function projectIntegrityObservation(observation, mapper, projectReference) {
+  return {
+    reference: projectReference(observation.reference),
+    source: observation.source,
+    id: mapper.id(observation.id),
+    ...observation.revision === void 0 ? {} : { revision: mapper.revision(observation.revision) },
+    path: mapper.path(observation.path),
+    ...observation.expectedId === void 0 ? {} : { expectedId: mapper.id(observation.expectedId) },
+    identity: observation.identity,
+    logicallyDeleted: observation.logicallyDeleted,
+    branch: observation.branch,
+    conflictCount: observation.conflictCount,
+    pathIsNFC: observation.pathIsNFC,
+    caseEquivalentPaths: observation.caseEquivalentPaths,
+    nfcEquivalentPaths: observation.nfcEquivalentPaths,
+    otherSourceGroup: observation.otherSourceGroup,
+    vault: {
+      reference: projectReference(observation.vault.reference),
+      status: observation.vault.status,
+      ...observation.vault.reason === void 0 ? {} : { reason: observation.vault.reason }
+    },
+    content: {
+      status: observation.content.status,
+      ...observation.content.reason === void 0 ? {} : { reason: observation.content.reason },
+      chunksRead: observation.content.chunksRead,
+      unavailableChunks: observation.content.unavailableChunks.map((chunk) => ({
+        id: mapper.chunk(chunk.id),
+        status: chunk.status
+      }))
+    },
+    comparisons: observation.comparisons.map((comparison) => ({
+      against: projectReference(comparison.against),
+      relation: comparison.relation
+    }))
+  };
+}
+function projectIntegrityError(error, mapper) {
+  return {
+    source: error.source,
+    reason: error.reason,
+    ...error.id === void 0 ? {} : { id: mapper.id(error.id) },
+    ...error.revision === void 0 ? {} : { revision: mapper.revision(error.revision) },
+    ...error.path === void 0 ? {} : { path: mapper.path(error.path) },
+    ...error.chunkId === void 0 ? {} : { chunkId: mapper.chunk(error.chunkId) }
+  };
+}
+function projectIntegrityReport(result, mapper, versions = {}) {
+  const safeReference = /^((local|remote):[0-9]+|vault:(local|remote):[0-9]+)$/;
+  const referenceAliases = /* @__PURE__ */ new Map();
+  const projectReference = (value) => {
+    if (safeReference.test(value)) return value;
+    const existing = referenceAliases.get(value);
+    if (existing !== void 0) return existing;
+    const alias = `finding-${String(referenceAliases.size + 1).padStart(3, "0")}`;
+    referenceAliases.set(value, alias);
+    return alias;
+  };
+  return {
+    schemaVersion: 1,
+    kind: "integrity",
+    status: result.status,
+    nameMode: mapper.mode,
+    versions: copyVersions(versions),
+    settings: {
+      encrypt: result.settings.encrypt,
+      usePathObfuscation: result.settings.usePathObfuscation,
+      handleFilenameCaseSensitive: result.settings.handleFilenameCaseSensitive,
+      idDerivationVersion: result.settings.idDerivationVersion,
+      pathNormalizationVersion: result.settings.pathNormalizationVersion
+    },
+    coverage: {
+      local: copyCoverage(result.coverage.local),
+      remote: copyCoverage(result.coverage.remote)
+    },
+    observations: result.observations.map(
+      (observation) => projectIntegrityObservation(observation, mapper, projectReference)
+    ),
+    errors: result.errors.map((error) => projectIntegrityError(error, mapper)),
+    scope: {
+      metadata: "normal-files-and-current-conflicts",
+      content: "suspect-groups-only",
+      history: "not-checked",
+      atomicSnapshot: false
+    }
+  };
+}
+function isOrphanRow(row) {
+  return row.id === "__orphan" && row.path === "__orphan" && row.title === "__orphan";
+}
+function projectUsageRow(row, mapper) {
+  const statistics = {
+    uniqueChunkCount: row.uniqueChunkCount,
+    sharedChunkCount: row.sharedChunkCount,
+    uniqueChunkSize: row.uniqueChunkSize,
+    sharedChunkSize: row.sharedChunkSize
+  };
+  if (isOrphanRow(row)) {
+    return {
+      title: "__orphan",
+      id: "__orphan",
+      path: "__orphan",
+      revision: "1-xxxxx",
+      rev: "1",
+      revHash: "xxxxx",
+      ...statistics
+    };
+  }
+  const path = mapper.path(row.path);
+  const revision = mapper.revision(row.revision);
+  return {
+    title: `${path} (${revision})`,
+    id: mapper.id(row.id),
+    path,
+    revision,
+    rev: row.rev,
+    revHash: mapper.mode === "pseudonym" ? revision : row.revHash,
+    ...statistics
+  };
+}
+function projectUsageError(error, mapper) {
+  return {
+    code: error.code,
+    ...error.id === void 0 ? {} : { id: mapper.id(error.id) },
+    ...error.revision === void 0 ? {} : { revision: mapper.revision(error.revision) }
+  };
+}
+function projectUsageReport(result, mapper, versions = {}) {
+  return {
+    version: 1,
+    kind: "usage",
+    status: result.status,
+    nameMode: mapper.mode,
+    versions: copyVersions(versions),
+    ...result.changedDuringRun === void 0 ? {} : { changedDuringRun: result.changedDuringRun },
+    rows: result.rows.map((row) => projectUsageRow(row, mapper)),
+    errors: result.errors.map((error) => projectUsageError(error, mapper))
+  };
+}
+const USAGE_COLUMNS = [
+  "title",
+  "id",
+  "path",
+  "rev",
+  "revHash",
+  "uniqueChunkCount",
+  "sharedChunkCount",
+  "uniqueChunkSize",
+  "sharedChunkSize"
+];
+const USAGE_HEADERS = [
+  "Title",
+  "Document ID",
+  "Path",
+  "Revision No",
+  "Revision Hash",
+  "Unique Chunk Count",
+  "Shared Chunk Count",
+  "Unique Chunk Size",
+  "Shared Chunk Size"
+];
+function escapeTSVField(value) {
+  const text = String(value);
+  return /[\t\r\n"]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+function formatUsageTSV(projected) {
+  const lines = [USAGE_HEADERS.map(escapeTSVField).join("	")];
+  for (const row of projected.rows) {
+    lines.push(USAGE_COLUMNS.map((column) => escapeTSVField(row[column])).join("	"));
+  }
+  return lines.join("\n");
+}
+function formatDiagnosticJSON(projected) {
+  return JSON.stringify(projected, null, 2);
+}
+function markdownCode(value) {
+  const text = value.replace(/\r\n?|\n|\t/g, " ").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  const backtickRuns = text.match(/`+/g) ?? [];
+  const fence = "`".repeat(Math.max(0, ...backtickRuns.map((run) => run.length)) + 1);
+  const padding = /^\s|\s$/.test(text) ? " " : "";
+  return `${fence}${padding}${text}${padding}${fence}`;
+}
+function renderMaybe(value) {
+  return value === void 0 ? "not recorded" : markdownCode(value);
+}
+function renderObservation(observation) {
+  const lines = [
+    `### ${markdownCode(observation.reference)}`,
+    `- Source: ${observation.source}`,
+    `- Path: ${markdownCode(observation.path)}`,
+    `- Document ID: ${markdownCode(observation.id)}`,
+    `- Revision: ${renderMaybe(observation.revision)}`,
+    `- Expected ID: ${renderMaybe(observation.expectedId)}`,
+    `- Identity: ${observation.identity}`,
+    `- Branch: ${observation.branch}`,
+    `- Logically deleted: ${observation.logicallyDeleted}`,
+    `- Conflict count: ${observation.conflictCount}`,
+    `- Path is NFC: ${observation.pathIsNFC}`,
+    `- Case-equivalent paths: ${observation.caseEquivalentPaths}`,
+    `- NFC-equivalent paths: ${observation.nfcEquivalentPaths}`,
+    `- Other inspected database group: ${observation.otherSourceGroup}`,
+    `- Vault content status: ${observation.vault.status}${observation.vault.reason === void 0 ? "" : ` (${observation.vault.reason})`}`,
+    `- Vault reference: ${markdownCode(observation.vault.reference)}`,
+    `- Content: ${observation.content.status}${observation.content.reason === void 0 ? "" : ` (${observation.content.reason})`}`,
+    `- Chunks read: ${observation.content.chunksRead}`
+  ];
+  if (observation.content.unavailableChunks.length > 0) {
+    lines.push(
+      `- Unavailable chunks: ${observation.content.unavailableChunks.map((chunk) => `${markdownCode(chunk.id)} (${chunk.status})`).join(", ")}`
+    );
+  }
+  if (observation.comparisons.length > 0) {
+    lines.push(
+      `- Comparisons: ${observation.comparisons.map((comparison) => `${markdownCode(comparison.against)}: ${comparison.relation}`).join("; ")}`
+    );
+  }
+  return lines;
+}
+function formatIntegrityMarkdown(projected) {
+  const observations = projected.observations;
+  const mismatchCount = observations.filter((observation) => observation.identity !== "consistent").length;
+  const conflictCount = observations.filter((observation) => observation.branch === "conflict").length;
+  const unavailableContentCount = observations.filter(
+    (observation) => observation.content.status === "missing" || observation.content.status === "unreadable"
+  ).length;
+  const unavailableChunkCount = observations.reduce(
+    (count, observation) => count + observation.content.unavailableChunks.length,
+    0
+  );
+  const coverageRows = [
+    ["Local", projected.coverage.local],
+    ["Remote", projected.coverage.remote]
+  ];
+  const lines = [
+    "# Database integrity report",
+    "",
+    `Status: ${projected.status}`,
+    `Names: ${projected.nameMode}`,
+    "",
+    "A complete status means the declared inspection finished. It does not mean that every finding is healthy.",
+    "Equal content applies only within the inspected scope and is not deletion advice.",
+    "",
+    "## Versions",
+    "",
+    ...projected.versions.commonlib === void 0 ? [] : [`- Commonlib version: ${markdownCode(projected.versions.commonlib)}`],
+    ...projected.versions.plugin === void 0 ? [] : [`- Plug-in version: ${markdownCode(projected.versions.plugin)}`],
+    ...projected.versions.application === void 0 ? [] : [`- Application version: ${markdownCode(projected.versions.application)}`],
+    ...projected.versions.commonlib === void 0 && projected.versions.plugin === void 0 && projected.versions.application === void 0 ? ["No version information was provided."] : [],
+    "",
+    "## Settings",
+    "",
+    `- Encryption: ${projected.settings.encrypt ? "enabled" : "disabled"}`,
+    `- Path obfuscation: ${projected.settings.usePathObfuscation ? "enabled" : "disabled"}`,
+    `- Filename case sensitivity: ${projected.settings.handleFilenameCaseSensitive ? "enabled" : "disabled"}`,
+    `- ID derivation version: ${projected.settings.idDerivationVersion}`,
+    `- Path normalisation version: ${projected.settings.pathNormalizationVersion}`,
+    "",
+    "## Scope",
+    "",
+    "- Metadata: normal files and current conflict branches",
+    "- Content: suspect groups only",
+    "- History: not checked",
+    "- Atomic snapshot: no",
+    "",
+    "## Coverage",
+    "",
+    "| Source | Status | Documents | Metadata | Excluded | Conflict branches | Content reads | Changed during run |",
+    "| --- | --- | ---: | ---: | ---: | ---: | ---: | --- |"
+  ];
+  for (const [source, coverage] of coverageRows) {
+    lines.push(
+      `| ${source} | ${coverage.status} | ${coverage.documents} | ${coverage.metadata} | ${coverage.excluded} | ${coverage.conflictBranches} | ${coverage.contentReads} | ${coverage.changedDuringRun} |`
+    );
+  }
+  lines.push(
+    "",
+    "## Counts",
+    "",
+    `- Identity mismatches: ${mismatchCount}`,
+    `- Conflict observations: ${conflictCount}`,
+    `- Missing or unreadable content observations: ${unavailableContentCount}`,
+    `- Unavailable chunks: ${unavailableChunkCount}`,
+    `- Errors: ${projected.errors.length}`,
+    "",
+    "## Findings",
+    ""
+  );
+  if (observations.length === 0) lines.push("No observations were returned.");
+  for (const observation of observations) lines.push(...renderObservation(observation), "");
+  if (projected.errors.length > 0) {
+    lines.push("## Errors", "");
+    for (const error of projected.errors) {
+      const details = [
+        `source=${error.source}`,
+        `reason=${error.reason}`,
+        ...error.id === void 0 ? [] : [`id=${markdownCode(error.id)}`],
+        ...error.revision === void 0 ? [] : [`revision=${markdownCode(error.revision)}`],
+        ...error.path === void 0 ? [] : [`path=${markdownCode(error.path)}`],
+        ...error.chunkId === void 0 ? [] : [`chunkId=${markdownCode(error.chunkId)}`]
+      ];
+      lines.push(`- ${details.join(", ")}`);
+    }
+  }
+  return lines.join("\n").trimEnd();
+}
+export {
+  createDiagnosticNameMapper,
+  formatDiagnosticJSON,
+  formatIntegrityMarkdown,
+  formatUsageTSV,
+  projectIntegrityReport,
+  projectUsageReport
+};

package/dist/diagnostics/types.d.ts

@@ -0,0 +1,130 @@
+import type { EntryDoc, MetaEntry } from "../common/types.js";
+import type { IPathService } from "../services/base/IService.js";
+export type DiagnosticStatus = "complete" | "partial" | "failed" | "cancelled";
+export type DiagnosticSourceName = "local" | "remote";
+export type DiagnosticNameMode = "original" | "pseudonym";
+export type DiagnosticReason = "source-unavailable" | "unsupported-remote" | "document-unreadable" | "revision-unavailable" | "invalid-metadata" | "unsupported-content" | "chunk-missing" | "chunk-unreadable" | "security-seed-unavailable" | "content-unreadable" | "source-changed" | "storage-changed" | "configuration-changed";
+export interface DiagnosticReadOptions {
+    rev?: string;
+    conflicts?: boolean;
+    revs?: boolean;
+    revs_info?: boolean;
+}
+/** Only these reads are available to an analyser; it cannot initialise or repair a database. */
+export interface DiagnosticDatabaseSource {
+    info(): Promise<{
+        update_seq?: string | number;
+    }>;
+    enumerateIds(): AsyncIterable<string>;
+    get(id: string, options?: DiagnosticReadOptions): Promise<EntryDoc>;
+}
+export interface DiagnosticError {
+    source: DiagnosticSourceName | "storage" | "configuration";
+    reason: DiagnosticReason;
+    id?: string;
+    revision?: string;
+    path?: string;
+    chunkId?: string;
+}
+export type DiagnosticContent = {
+    status: "available";
+    bytes: Uint8Array<ArrayBuffer>;
+    reason?: never;
+} | {
+    status: "missing" | "unreadable" | "not-checked";
+    reason?: DiagnosticReason;
+};
+export interface DiagnosticCoverage {
+    status: "complete" | "partial" | "failed" | "not-checked";
+    documents: number;
+    metadata: number;
+    excluded: number;
+    conflictBranches: number;
+    contentReads: number;
+    changedDuringRun: boolean;
+}
+export interface DiagnosticObservation {
+    reference: string;
+    source: DiagnosticSourceName;
+    id: string;
+    revision?: string;
+    /** Exact stored spelling, retained independently of the host's identity normalisation. */
+    path: string;
+    expectedId?: string;
+    identity: "consistent" | "document-id-mismatch" | "namespace-mismatch";
+    logicallyDeleted: boolean;
+    branch: "winner" | "conflict";
+    conflictCount: number;
+    pathIsNFC: boolean;
+    caseEquivalentPaths: boolean;
+    nfcEquivalentPaths: boolean;
+    /** Presence of this identity/path group in the other inspected database. */
+    otherSourceGroup: "present" | "missing" | "not-checked";
+    vault: {
+        reference: string;
+        status: DiagnosticContent["status"];
+        reason?: DiagnosticReason;
+    };
+    content: {
+        status: DiagnosticContent["status"];
+        reason?: DiagnosticReason;
+        chunksRead: number;
+        unavailableChunks: {
+            id: string;
+            status: "missing" | "unreadable";
+        }[];
+    };
+    comparisons: {
+        against: string;
+        relation: "equal" | "different" | "unavailable" | "not-checked";
+    }[];
+}
+/** A whitelist: connection details, keys, and passphrases have no report field. */
+export interface DiagnosticIdentitySettings {
+    encrypt: boolean;
+    usePathObfuscation: boolean;
+    handleFilenameCaseSensitive: boolean;
+    idDerivationVersion: number;
+    pathNormalizationVersion: number;
+}
+export interface DatabaseIntegrityResult {
+    schemaVersion: 1;
+    kind: "integrity";
+    status: DiagnosticStatus;
+    settings: DiagnosticIdentitySettings;
+    coverage: Record<DiagnosticSourceName, DiagnosticCoverage>;
+    observations: DiagnosticObservation[];
+    errors: DiagnosticError[];
+    /** Scope declarations are part of every report, including a successful one. */
+    scope: {
+        metadata: "normal-files-and-current-conflicts";
+        content: "suspect-groups-only";
+        history: "not-checked";
+        atomicSnapshot: false;
+    };
+}
+export interface DatabaseIntegrityOptions {
+    local: DiagnosticDatabaseSource;
+    remote?: () => Promise<DiagnosticDatabaseSource & {
+        close(): Promise<void>;
+    }>;
+    remoteUnavailableReason?: "unsupported-remote" | "source-unavailable";
+    path: Pick<IPathService, "getPath" | "path2id">;
+    settings: DiagnosticIdentitySettings;
+    readStorage(path: string): Promise<DiagnosticContent>;
+    /** Captures profile and relevant settings identity without exporting it. */
+    isConfigurationCurrent(): boolean;
+    signal?: AbortSignal;
+    onProgress?(progress: {
+        phase: "metadata" | "content";
+        processed: number;
+    }): void;
+}
+export declare class DiagnosticReadError extends Error {
+    readonly reason: DiagnosticReason;
+    readonly missing: boolean;
+    constructor(reason: DiagnosticReason, missing?: boolean);
+}
+export type InspectedMetadata = MetaEntry & {
+    _conflicts?: string[];
+};

package/dist/diagnostics/types.js

@@ -0,0 +1,13 @@
+class DiagnosticReadError extends Error {
+  constructor(reason, missing = false) {
+    super(reason);
+    this.reason = reason;
+    this.missing = missing;
+    this.name = "DiagnosticReadError";
+  }
+  reason;
+  missing;
+}
+export {
+  DiagnosticReadError
+};

package/dist/diagnostics/usage.d.ts

@@ -0,0 +1,51 @@
+export interface DatabaseUsageGetOptions {
+    revs?: boolean;
+    revs_info?: boolean;
+    conflicts?: boolean;
+    rev?: string;
+}
+export interface DatabaseUsageSource {
+    info(): Promise<{
+        update_seq?: string | number;
+    }>;
+    enumerateIds(): AsyncIterable<string>;
+    get(id: string, options?: DatabaseUsageGetOptions): Promise<object | null | undefined>;
+}
+export interface DatabaseUsageProgress {
+    idsProcessed: number;
+    revisionsProcessed: number;
+}
+export type DatabaseUsageStatus = "complete" | "partial" | "failed" | "cancelled";
+export type DatabaseUsageErrorCode = "start_info_read_failed" | "start_update_seq_unavailable" | "end_info_read_failed" | "end_update_seq_unavailable" | "configuration_changed" | "id_enumeration_failed" | "revision_list_read_failed" | "revision_not_found" | "revision_read_failed" | "revision_document_invalid";
+export interface DatabaseUsageError {
+    code: DatabaseUsageErrorCode;
+    id?: string;
+    revision?: string;
+}
+export interface DatabaseUsageRow {
+    title: string;
+    id: string;
+    path: string;
+    revision: string;
+    rev: string;
+    revHash: string;
+    uniqueChunkCount: number;
+    sharedChunkCount: number;
+    uniqueChunkSize: number;
+    sharedChunkSize: number;
+}
+export interface DatabaseUsageResult {
+    version: 1;
+    kind: "usage";
+    status: DatabaseUsageStatus;
+    startUpdateSeq?: string | number;
+    endUpdateSeq?: string | number;
+    changedDuringRun?: boolean;
+    rows: DatabaseUsageRow[];
+    errors: DatabaseUsageError[];
+}
+export declare function analyseDatabaseUsage(options: {
+    source: DatabaseUsageSource;
+    signal?: AbortSignal;
+    onProgress?: (progress: DatabaseUsageProgress) => void;
+}): Promise<DatabaseUsageResult>;