@vrtmrz/livesync-commonlib 0.1.42 → 0.1.44

package/dist/diagnostics/local.d.ts

@@ -0,0 +1,4 @@
+import type { EntryDoc } from "../common/types.js";
+import type { DiagnosticDatabaseSource } from "./types.js";
+/** Wrap an existing local handle without taking ownership or using chunk caches. */
+export declare function createLocalDiagnosticSource(database: Pick<PouchDB.Database<EntryDoc>, "info" | "allDocs" | "get">): DiagnosticDatabaseSource;

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/names.d.ts

@@ -0,0 +1,16 @@
+import type { DiagnosticNameMode } from "./types.js";
+export interface DiagnosticNameMapper {
+    readonly mode: DiagnosticNameMode;
+    readonly salt?: string;
+    path(value: string): string;
+    id(value: string): string;
+    revision(value: string): string;
+    chunk(value: string): string;
+}
+/** Reads only a complete version-one path token, never a document or revision alias. */
+export declare function parseDiagnosticPathToken(value: string): {
+    salt: string;
+    hash: string;
+} | undefined;
+/** Reuses public report salts without storing paths or a correspondence table outside this mapper. */
+export declare function createDiagnosticNameMapper(mode: DiagnosticNameMode, suppliedSalt?: string): DiagnosticNameMapper;

package/dist/diagnostics/names.js

@@ -0,0 +1,50 @@
+import { Sha256 } from "@aws-crypto/sha256-js";
+const SALT_PATTERN = /^[A-Za-z0-9_-]{8}$/;
+function parseDiagnosticPathToken(value) {
+  const match = /^([A-Za-z0-9_-]{8})\$([0-9a-f]{32})$/.exec(value);
+  return match ? { salt: match[1], hash: match[2] } : void 0;
+}
+function randomSalt() {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(6));
+  return btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_");
+}
+function nameHash(salt, domain, value) {
+  const hash = new Sha256();
+  hash.update(JSON.stringify(["livesync-diagnostic-v1", salt, domain, value]));
+  return Array.from(hash.digestSync().subarray(0, 16), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function createDiagnosticNameMapper(mode, suppliedSalt) {
+  if (mode === "original") {
+    const original = (value) => value;
+    return { mode, path: original, id: original, revision: original, chunk: original };
+  }
+  const salt = suppliedSalt ?? randomSalt();
+  if (!SALT_PATTERN.test(salt)) throw new Error("Invalid diagnostic salt");
+  const domainMapper = (domain, format) => {
+    const aliases = /* @__PURE__ */ new Map();
+    return (value) => {
+      const existing = aliases.get(value);
+      if (existing !== void 0) return existing;
+      const alias = format(nameHash(salt, domain, value), value);
+      if (aliases.size >= 4096) aliases.clear();
+      aliases.set(value, alias);
+      return alias;
+    };
+  };
+  return {
+    mode,
+    salt,
+    path: domainMapper("path", (hash) => `${salt}$${hash}`),
+    id: domainMapper("document", (hash) => `document-${hash}`),
+    revision: domainMapper("revision", (hash, value) => {
+      const generation = /^([1-9][0-9]*)-.+$/.exec(value)?.[1];
+      const prefix = generation !== void 0 && Number.isSafeInteger(Number(generation)) ? `${generation}-` : "";
+      return `${prefix}psu${hash}`;
+    }),
+    chunk: domainMapper("chunk", (hash) => `chunk-${hash}`)
+  };
+}
+export {
+  createDiagnosticNameMapper,
+  parseDiagnosticPathToken
+};

package/dist/diagnostics/reports.d.ts

@@ -0,0 +1,111 @@
+import type { DatabaseIntegrityResult, DiagnosticCoverage, DiagnosticError, DiagnosticIdentitySettings, DiagnosticNameMode, DiagnosticObservation, DiagnosticPathEquivalenceGroup, DiagnosticSourceName, DiagnosticStatus } from "./types.js";
+import type { DatabaseUsageError, DatabaseUsageResult, DatabaseUsageStatus } from "./usage.js";
+import type { DiagnosticNameMapper } from "./names.js";
+export { createDiagnosticNameMapper, parseDiagnosticPathToken } from "./names.js";
+export type { DiagnosticNameMapper } from "./names.js";
+export interface DiagnosticReportVersions {
+    commonlib?: string;
+    plugin?: string;
+    application?: string;
+}
+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;
+    caseEquivalentGroup?: string;
+    nfcEquivalentGroup?: string;
+    metadata?: DiagnosticObservation["metadata"];
+    otherSourceGroup: DiagnosticObservation["otherSourceGroup"];
+    vault: {
+        reference: string;
+        status: DiagnosticObservation["vault"]["status"];
+        reason?: DiagnosticObservation["vault"]["reason"];
+        size?: number;
+        contentSizeDifference?: number;
+        mtimeDifferenceMs?: number;
+    };
+    content: {
+        status: DiagnosticObservation["content"]["status"];
+        reason?: DiagnosticObservation["content"]["reason"];
+        chunksRead: number;
+        unavailableChunks: {
+            id: string;
+            status: "missing" | "unreadable";
+        }[];
+        size?: number;
+        recordedSizeDifference?: number;
+    };
+    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[];
+    pathEquivalenceGroups?: DiagnosticPathEquivalenceGroup[];
+    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;