@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

@@ -1,661 +0,0 @@
-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(),
-  });
-}