@beyondwork/docx-react-component 1.0.0

package/services/react-word-editor/lib/certification-store.ts

@@ -0,0 +1,661 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  getHarnessExport,
+  getHarnessSession,
+  getHarnessStorageAssumptions,
+  getHarnessValidationRun,
+  listHarnessSessions,
+  listHarnessValidationRuns,
+  listHarnessExportsForSession,
+  type HarnessExportRecord,
+  type HarnessValidationRunRecord,
+} from "./storage.ts";
+
+export const CERTIFICATION_STORE_INDEX_VERSION = "react-word-editor-certification/1";
+
+export type CertificationSurface = "word-desktop" | "word-web";
+export type CertificationOutcome = "not-reviewed" | "passed" | "issues-found";
+export type CertificationTargetType = "validation-run" | "export-artifact";
+
+type CertificationIndex = {
+  version: typeof CERTIFICATION_STORE_INDEX_VERSION;
+  certifications: ManualCertificationRecord[];
+};
+
+export type ManualCertificationRecord = {
+  certificationId: string;
+  createdAt: string;
+  updatedAt: string;
+  observedAt: string;
+  operator: string;
+  surface: CertificationSurface;
+  outcome: CertificationOutcome;
+  summary: string;
+  notes?: string;
+  targetType: CertificationTargetType;
+  targetId: string;
+  runId?: string;
+  exportId?: string;
+  sessionId?: string;
+  sourceId?: string;
+  fileName: string;
+  sourceLabel?: string;
+  validatorSnapshot?: {
+    isValid: boolean;
+    packageFindingCount: number;
+    sdkFindingCount: number;
+  };
+};
+
+export type CertificationOutcomeSummary = {
+  outcome: CertificationOutcome;
+  label: string;
+  tone: "neutral" | "success" | "warning";
+};
+
+export type CertificationSurfaceStatus = CertificationOutcomeSummary & {
+  surface: CertificationSurface;
+  latestCertificationId?: string;
+  latestObservedAt?: string;
+  operator?: string;
+  summary?: string;
+};
+
+export type CertificationTargetSummary = {
+  targetType: CertificationTargetType;
+  targetId: string;
+  fileName: string;
+  sourceLabel?: string;
+  sessionId?: string;
+  sourceId?: string;
+  runId?: string;
+  exportId?: string;
+  certificationCount: number;
+  latestObservedAt?: string;
+  desktop: CertificationSurfaceStatus;
+  web: CertificationSurfaceStatus;
+};
+
+export type CertificationDashboardCandidate = CertificationTargetSummary & {
+  kindLabel: string;
+  createdAt: string;
+  detail: string;
+  validatorDetail?: string;
+};
+
+export type CertificationDashboardModel = {
+  summary: {
+    certifications: number;
+    targets: number;
+    desktopReviewed: number;
+    desktopPending: number;
+    webReviewed: number;
+    webPending: number;
+  };
+  recentCertifications: ManualCertificationRecord[];
+  validationCandidates: CertificationDashboardCandidate[];
+  exportCandidates: CertificationDashboardCandidate[];
+  storage: {
+    activeStorageDir: string;
+    configuredStorageDir?: string;
+    storageMode: string;
+    indexVersion: typeof CERTIFICATION_STORE_INDEX_VERSION;
+  };
+};
+
+export class CertificationStoreError extends Error {
+  readonly code: string;
+  readonly status: number;
+
+  constructor(code: string, status: number, message: string) {
+    super(message);
+    this.name = "CertificationStoreError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export function isCertificationStoreError(error: unknown): error is CertificationStoreError {
+  return error instanceof CertificationStoreError;
+}
+
+type CreateManualCertificationInput = {
+  operator: string;
+  surface: CertificationSurface;
+  outcome: CertificationOutcome;
+  summary: string;
+  notes?: string;
+  observedAt?: string;
+  targetType: CertificationTargetType;
+  targetId: string;
+};
+
+type ResolvedCertificationTarget = {
+  targetType: CertificationTargetType;
+  targetId: string;
+  runId?: string;
+  exportId?: string;
+  sessionId?: string;
+  sourceId?: string;
+  fileName: string;
+  sourceLabel?: string;
+  validatorSnapshot?: ManualCertificationRecord["validatorSnapshot"];
+};
+
+const moduleDirPath = path.dirname(fileURLToPath(import.meta.url));
+const serviceRootDir = path.resolve(moduleDirPath, "..");
+const defaultStorageDir = path.join(serviceRootDir, ".tmp/react-word-editor-harness");
+
+function getConfiguredStorageDir(): string | undefined {
+  const value = process.env.HARNESS_STORAGE_DIR?.trim();
+  return value ? value : undefined;
+}
+
+function getStorageDir(): string {
+  return getConfiguredStorageDir() || defaultStorageDir;
+}
+
+function getCertificationIndexPath(storageDir: string): string {
+  return path.join(storageDir, "certifications.json");
+}
+
+function createEmptyIndex(): CertificationIndex {
+  return {
+    version: CERTIFICATION_STORE_INDEX_VERSION,
+    certifications: [],
+  };
+}
+
+function normalizeIndex(raw: unknown): CertificationIndex {
+  if (!raw || typeof raw !== "object") {
+    return createEmptyIndex();
+  }
+
+  const candidate = raw as Partial<CertificationIndex>;
+
+  return {
+    version: CERTIFICATION_STORE_INDEX_VERSION,
+    certifications: Array.isArray(candidate.certifications) ? candidate.certifications : [],
+  };
+}
+
+async function ensureCertificationStoreLayout(): Promise<string> {
+  const storageDir = getStorageDir();
+  await mkdir(storageDir, { recursive: true });
+
+  const indexPath = getCertificationIndexPath(storageDir);
+
+  try {
+    await stat(indexPath);
+  } catch {
+    await writeFile(indexPath, JSON.stringify(createEmptyIndex(), null, 2));
+  }
+
+  return storageDir;
+}
+
+async function readIndex(): Promise<CertificationIndex> {
+  const storageDir = await ensureCertificationStoreLayout();
+  const raw = await readFile(getCertificationIndexPath(storageDir), "utf8");
+  const normalized = normalizeIndex(JSON.parse(raw));
+  const serialized = JSON.stringify(normalized, null, 2);
+
+  if (raw !== serialized) {
+    await writeIndex(normalized);
+  }
+
+  return normalized;
+}
+
+async function writeIndex(index: CertificationIndex): Promise<void> {
+  const storageDir = await ensureCertificationStoreLayout();
+  const normalized = normalizeIndex(index);
+  const indexPath = getCertificationIndexPath(storageDir);
+  const tempPath = `${indexPath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(tempPath, JSON.stringify(normalized, null, 2));
+  await rename(tempPath, indexPath);
+}
+
+function isCertificationSurface(value: string): value is CertificationSurface {
+  return value === "word-desktop" || value === "word-web";
+}
+
+function isCertificationOutcome(value: string): value is CertificationOutcome {
+  return value === "not-reviewed" || value === "passed" || value === "issues-found";
+}
+
+function isCertificationTargetType(value: string): value is CertificationTargetType {
+  return value === "validation-run" || value === "export-artifact";
+}
+
+function sanitizeOptionalText(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function summarizeOutcome(outcome: CertificationOutcome): CertificationOutcomeSummary {
+  if (outcome === "passed") {
+    return {
+      outcome,
+      label: "reviewed and passed",
+      tone: "success",
+    };
+  }
+
+  if (outcome === "issues-found") {
+    return {
+      outcome,
+      label: "issues recorded",
+      tone: "warning",
+    };
+  }
+
+  return {
+    outcome,
+    label: "not yet reviewed",
+    tone: "neutral",
+  };
+}
+
+function buildPendingSurfaceStatus(surface: CertificationSurface): CertificationSurfaceStatus {
+  const summary = summarizeOutcome("not-reviewed");
+
+  return {
+    surface,
+    ...summary,
+  };
+}
+
+async function resolveCertificationTarget(
+  targetType: CertificationTargetType,
+  targetId: string,
+): Promise<ResolvedCertificationTarget> {
+  if (targetType === "validation-run") {
+    const run = await getHarnessValidationRun(targetId);
+
+    if (!run) {
+      throw new CertificationStoreError(
+        "unknown_validation_run",
+        404,
+        `Validation run ${targetId} does not exist.`,
+      );
+    }
+
+    const session = run.sessionId ? await getHarnessSession(run.sessionId) : undefined;
+
+    return {
+      targetType,
+      targetId,
+      runId: run.runId,
+      exportId: run.exportId,
+      sessionId: run.sessionId,
+      sourceId: run.sourceId ?? session?.sourceId,
+      fileName: run.fileName,
+      sourceLabel: session?.sourceLabel,
+      validatorSnapshot: {
+        isValid: run.summary.isValid,
+        packageFindingCount: run.summary.packageFindingCount,
+        sdkFindingCount: run.summary.sdkFindingCount,
+      },
+    };
+  }
+
+  const exportRecord = await getHarnessExport(targetId);
+
+  if (!exportRecord) {
+    throw new CertificationStoreError(
+      "unknown_export",
+      404,
+      `Export ${targetId} does not exist.`,
+    );
+  }
+
+  const session = await getHarnessSession(exportRecord.sessionId);
+
+  return {
+    targetType,
+    targetId,
+    exportId: exportRecord.exportId,
+    sessionId: exportRecord.sessionId,
+    sourceId: session?.sourceId,
+    fileName: exportRecord.fileName,
+    sourceLabel: session?.sourceLabel,
+  };
+}
+
+function createStatusMap(records: ManualCertificationRecord[]): Map<string, CertificationTargetSummary> {
+  const map = new Map<string, CertificationTargetSummary>();
+
+  for (const record of records) {
+    const key = `${record.targetType}:${record.targetId}`;
+    const existing = map.get(key) ?? {
+      targetType: record.targetType,
+      targetId: record.targetId,
+      fileName: record.fileName,
+      sourceLabel: record.sourceLabel,
+      sessionId: record.sessionId,
+      sourceId: record.sourceId,
+      runId: record.runId,
+      exportId: record.exportId,
+      certificationCount: 0,
+      latestObservedAt: undefined,
+      desktop: buildPendingSurfaceStatus("word-desktop"),
+      web: buildPendingSurfaceStatus("word-web"),
+    };
+
+    existing.certificationCount += 1;
+    existing.fileName = record.fileName;
+    existing.sourceLabel = record.sourceLabel ?? existing.sourceLabel;
+    existing.sessionId = record.sessionId ?? existing.sessionId;
+    existing.sourceId = record.sourceId ?? existing.sourceId;
+    existing.runId = record.runId ?? existing.runId;
+    existing.exportId = record.exportId ?? existing.exportId;
+
+    if (!existing.latestObservedAt || record.observedAt > existing.latestObservedAt) {
+      existing.latestObservedAt = record.observedAt;
+    }
+
+    const currentSurface =
+      record.surface === "word-desktop" ? existing.desktop : existing.web;
+
+    if (!currentSurface.latestObservedAt || record.observedAt >= currentSurface.latestObservedAt) {
+      const summary = summarizeOutcome(record.outcome);
+      const nextSurface: CertificationSurfaceStatus = {
+        surface: record.surface,
+        ...summary,
+        latestCertificationId: record.certificationId,
+        latestObservedAt: record.observedAt,
+        operator: record.operator,
+        summary: record.summary,
+      };
+
+      if (record.surface === "word-desktop") {
+        existing.desktop = nextSurface;
+      } else {
+        existing.web = nextSurface;
+      }
+    }
+
+    map.set(key, existing);
+  }
+
+  return map;
+}
+
+function formatValidatorDetail(run: HarnessValidationRunRecord): string {
+  if (run.summary.isValid) {
+    return "validator snapshot clean";
+  }
+
+  const findingCount = run.summary.packageFindingCount + run.summary.sdkFindingCount;
+  return `${findingCount} validator finding${findingCount === 1 ? "" : "s"} stored`;
+}
+
+function buildValidationCandidate(
+  run: HarnessValidationRunRecord,
+  summary?: CertificationTargetSummary,
+): CertificationDashboardCandidate {
+  return {
+    targetType: "validation-run",
+    targetId: run.runId,
+    fileName: summary?.fileName ?? run.fileName,
+    sourceLabel: summary?.sourceLabel,
+    sessionId: summary?.sessionId ?? run.sessionId,
+    sourceId: summary?.sourceId ?? run.sourceId,
+    runId: run.runId,
+    exportId: summary?.exportId ?? run.exportId,
+    certificationCount: summary?.certificationCount ?? 0,
+    latestObservedAt: summary?.latestObservedAt,
+    desktop: summary?.desktop ?? buildPendingSurfaceStatus("word-desktop"),
+    web: summary?.web ?? buildPendingSurfaceStatus("word-web"),
+    kindLabel: "Validation run",
+    createdAt: run.createdAt,
+    detail: `target ${run.targetType}${run.exportId ? ` · export ${run.exportId.slice(0, 8)}` : ""}`,
+    validatorDetail: formatValidatorDetail(run),
+  };
+}
+
+async function listRecentExportCandidates(): Promise<HarnessExportRecord[]> {
+  const sessions = await listHarnessSessions();
+  const results: HarnessExportRecord[] = [];
+  const seen = new Set<string>();
+
+  for (const session of sessions) {
+    const exports = await listHarnessExportsForSession(session.sessionId);
+
+    for (const record of exports) {
+      if (!seen.has(record.exportId)) {
+        seen.add(record.exportId);
+        results.push(record);
+      }
+
+      if (results.length >= 12) {
+        return results;
+      }
+    }
+  }
+
+  return results;
+}
+
+async function buildExportCandidate(
+  exportRecord: HarnessExportRecord,
+  summary?: CertificationTargetSummary,
+): Promise<CertificationDashboardCandidate> {
+  const session = await getHarnessSession(exportRecord.sessionId);
+  const relatedRun = exportRecord.exportId
+    ? await findLatestValidationRunForExport(exportRecord.exportId)
+    : undefined;
+
+  return {
+    targetType: "export-artifact",
+    targetId: exportRecord.exportId,
+    fileName: summary?.fileName ?? exportRecord.fileName,
+    sourceLabel: summary?.sourceLabel ?? session?.sourceLabel,
+    sessionId: summary?.sessionId ?? exportRecord.sessionId,
+    sourceId: summary?.sourceId ?? session?.sourceId,
+    runId: summary?.runId ?? relatedRun?.runId,
+    exportId: exportRecord.exportId,
+    certificationCount: summary?.certificationCount ?? 0,
+    latestObservedAt: summary?.latestObservedAt,
+    desktop: summary?.desktop ?? buildPendingSurfaceStatus("word-desktop"),
+    web: summary?.web ?? buildPendingSurfaceStatus("word-web"),
+    kindLabel: "Export artifact",
+    createdAt: exportRecord.createdAt,
+    detail: `${exportRecord.byteLength.toLocaleString()} bytes${session ? ` · session ${session.sessionId.slice(0, 8)}` : ""}`,
+    validatorDetail: relatedRun ? formatValidatorDetail(relatedRun) : "no validator snapshot linked yet",
+  };
+}
+
+async function findLatestValidationRunForExport(
+  exportId: string,
+): Promise<HarnessValidationRunRecord | undefined> {
+  const runs = await listHarnessValidationRuns();
+  return runs.find((run) => run.exportId === exportId);
+}
+
+export function getCertificationStoreSnapshot() {
+  const assumptions = getHarnessStorageAssumptions();
+
+  return {
+    activeStorageDir: assumptions.activeStorageDir,
+    configuredStorageDir: assumptions.configuredStorageDir,
+    storageMode: assumptions.storageMode,
+    indexVersion: CERTIFICATION_STORE_INDEX_VERSION,
+  };
+}
+
+export async function listManualCertifications(): Promise<ManualCertificationRecord[]> {
+  const index = await readIndex();
+  return index.certifications
+    .slice()
+    .sort((a, b) => b.observedAt.localeCompare(a.observedAt) || b.createdAt.localeCompare(a.createdAt));
+}
+
+export async function createManualCertification(
+  input: CreateManualCertificationInput,
+): Promise<ManualCertificationRecord> {
+  const operator = input.operator.trim();
+  const summary = input.summary.trim();
+  const notes = sanitizeOptionalText(input.notes);
+
+  if (!operator) {
+    throw new CertificationStoreError("missing_operator", 400, "Certification requires an operator name.");
+  }
+
+  if (!summary) {
+    throw new CertificationStoreError("missing_summary", 400, "Certification requires a concise evidence summary.");
+  }
+
+  const resolvedTarget = await resolveCertificationTarget(input.targetType, input.targetId);
+  const now = new Date().toISOString();
+  const observedAtRaw = sanitizeOptionalText(input.observedAt);
+  const observedAtDate = observedAtRaw ? new Date(observedAtRaw) : undefined;
+
+  if (observedAtDate && Number.isNaN(observedAtDate.getTime())) {
+    throw new CertificationStoreError(
+      "invalid_observed_at",
+      400,
+      "Certification observedAt must be a valid timestamp.",
+    );
+  }
+
+  const observedAt = observedAtDate ? observedAtDate.toISOString() : now;
+
+  const record: ManualCertificationRecord = {
+    certificationId: randomUUID(),
+    createdAt: now,
+    updatedAt: now,
+    observedAt,
+    operator,
+    surface: input.surface,
+    outcome: input.outcome,
+    summary,
+    notes,
+    targetType: resolvedTarget.targetType,
+    targetId: resolvedTarget.targetId,
+    runId: resolvedTarget.runId,
+    exportId: resolvedTarget.exportId,
+    sessionId: resolvedTarget.sessionId,
+    sourceId: resolvedTarget.sourceId,
+    fileName: resolvedTarget.fileName,
+    sourceLabel: resolvedTarget.sourceLabel,
+    validatorSnapshot: resolvedTarget.validatorSnapshot,
+  };
+
+  const index = await readIndex();
+  index.certifications.unshift(record);
+  await writeIndex(index);
+
+  return record;
+}
+
+export async function getCertificationDashboardModel(): Promise<CertificationDashboardModel> {
+  const [records, validationRuns, exportRecords] = await Promise.all([
+    listManualCertifications(),
+    listHarnessValidationRuns({ limit: 12 }),
+    listRecentExportCandidates(),
+  ]);
+  const statusMap = createStatusMap(records);
+
+  const validationCandidates = validationRuns.map((run) =>
+    buildValidationCandidate(run, statusMap.get(`validation-run:${run.runId}`)),
+  );
+  const exportCandidates = await Promise.all(
+    exportRecords.map((record) =>
+      buildExportCandidate(record, statusMap.get(`export-artifact:${record.exportId}`)),
+    ),
+  );
+
+  const targets = [...validationCandidates, ...exportCandidates];
+  const desktopReviewed = targets.filter(
+    (target) => target.desktop.outcome !== "not-reviewed",
+  ).length;
+  const webReviewed = targets.filter((target) => target.web.outcome !== "not-reviewed").length;
+
+  return {
+    summary: {
+      certifications: records.length,
+      targets: targets.length,
+      desktopReviewed,
+      desktopPending: targets.length - desktopReviewed,
+      webReviewed,
+      webPending: targets.length - webReviewed,
+    },
+    recentCertifications: records.slice(0, 12),
+    validationCandidates,
+    exportCandidates,
+    storage: getCertificationStoreSnapshot(),
+  };
+}
+
+export async function getCertificationTargetSelection(input?: {
+  targetType?: string;
+  targetId?: string;
+}): Promise<CertificationDashboardCandidate | undefined> {
+  const model = await getCertificationDashboardModel();
+  const allTargets = [...model.validationCandidates, ...model.exportCandidates];
+
+  if (input?.targetType && input.targetId && isCertificationTargetType(input.targetType)) {
+    return allTargets.find(
+      (target) =>
+        target.targetType === input.targetType && target.targetId === input.targetId,
+    );
+  }
+
+  return allTargets[0];
+}
+
+export async function parseAndCreateManualCertification(input: {
+  operator?: string;
+  surface?: string;
+  outcome?: string;
+  summary?: string;
+  notes?: string;
+  observedAt?: string;
+  targetType?: string;
+  targetId?: string;
+}): Promise<ManualCertificationRecord> {
+  if (!input.targetType || !isCertificationTargetType(input.targetType)) {
+    throw new CertificationStoreError(
+      "invalid_target_type",
+      400,
+      "Certification requires `targetType` of `validation-run` or `export-artifact`.",
+    );
+  }
+
+  if (!input.targetId?.trim()) {
+    throw new CertificationStoreError("missing_target_id", 400, "Certification requires a target id.");
+  }
+
+  if (!input.surface || !isCertificationSurface(input.surface)) {
+    throw new CertificationStoreError(
+      "invalid_surface",
+      400,
+      "Certification requires `surface` of `word-desktop` or `word-web`.",
+    );
+  }
+
+  if (!input.outcome || !isCertificationOutcome(input.outcome)) {
+    throw new CertificationStoreError(
+      "invalid_outcome",
+      400,
+      "Certification requires `outcome` of `not-reviewed`, `passed`, or `issues-found`.",
+    );
+  }
+
+  return createManualCertification({
+    operator: input.operator ?? "",
+    surface: input.surface,
+    outcome: input.outcome,
+    summary: input.summary ?? "",
+    notes: input.notes,
+    observedAt: input.observedAt,
+    targetType: input.targetType,
+    targetId: input.targetId.trim(),
+  });
+}