@oscharko-dev/keiko-evidence 0.2.0

package/dist/qualityIntelligence/figmaSnapshot/schema.js

@@ -0,0 +1,163 @@
+// Persisted Figma Snapshot evidence record (Epic #750, Issue #753, ADR-0023 evidence discipline).
+//
+// The immutable, redaction-safe on-disk shape of a Figma Snapshot. It mirrors the QI evidence
+// manifest posture: a breaking change introduces a NEW `figmaSnapshotSchemaVersion` literal rather
+// than mutating this one; every string leaf has passed through redaction before persist; NO token,
+// NO secret, NO outbound Figma/render URL, NO header reaches this shape.
+//
+// The rendered PNG bytes do NOT live inline — they are written as binary side-files and referenced
+// here by relative path + sha256 (the same tamper-evidence pattern as ADR-0017 side-files). The
+// integrity hashes follow the server builder's deterministic hash projection but are recomputed by
+// the evidence store after redaction so they describe the exact persisted artifact. A loaded record
+// can then be drift-checked against #735. Optional #752 metadata (`links`, `tokens`) keeps separate
+// artifact hashes: they are not drift identity, but downstream consumers must not trust a tampered
+// artifact under an otherwise-valid drift hash.
+//
+// `irJson` is the structural Screen-IR (#752) serialised as an opaque JSON value. It is design
+// CONTENT — the artifact's purpose — and is kept (not redacted away); only secrets are stripped.
+export const FIGMA_SNAPSHOT_SCHEMA_VERSION = 1;
+const ALLOWED_TOP_LEVEL_KEYS = new Set([
+    "figmaSnapshotSchemaVersion",
+    "runId",
+    "provenance",
+    "screens",
+    "skippedScreens",
+    "structuralScreens",
+    "links",
+    "tokens",
+    "metrics",
+    "artifactHashes",
+    "integrityHash",
+    "redactionSummary",
+]);
+const ALLOWED_ARTIFACT_HASH_KEYS = new Set([
+    "links",
+    "tokens",
+    "metrics",
+]);
+const ALLOWED_METRICS_KEYS = new Set([
+    "reductionRatio",
+    "screenCount",
+    "renderCount",
+    "designTokenCount",
+    "augmentation",
+    "navGraph",
+    "a11y",
+]);
+const ALLOWED_AUGMENTATION_KEYS = new Set([
+    "deterministic",
+    "modelAugmented",
+    "modelAugmentedShare",
+]);
+const ALLOWED_NAV_GRAPH_KEYS = new Set(["screens", "transitions"]);
+const ALLOWED_A11Y_KEYS = new Set(["findings"]);
+const REQUIRED_METRIC_KEYS = [
+    "reductionRatio",
+    "screenCount",
+    "renderCount",
+    "designTokenCount",
+];
+function validateArtifactHashes(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, reason: "artifactHashes must be an object" };
+    }
+    for (const key of Object.keys(value)) {
+        if (!ALLOWED_ARTIFACT_HASH_KEYS.has(key)) {
+            return { ok: false, reason: `unknown artifactHashes key: ${key}` };
+        }
+    }
+    return undefined;
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function keysAllowed(value, allowed) {
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+function validateObjectNumbers(value, allowed, required, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, reason: `${label} must be an object` };
+    }
+    const record = value;
+    if (!keysAllowed(record, allowed)) {
+        return { ok: false, reason: `${label} has unknown keys` };
+    }
+    for (const key of required) {
+        if (!finiteNumber(record[key]))
+            return { ok: false, reason: `${label}.${key} must be a number` };
+    }
+    return undefined;
+}
+function validateRequiredNumbers(record, keys, label) {
+    for (const key of keys) {
+        if (!finiteNumber(record[key]))
+            return { ok: false, reason: `${label}.${key} must be a number` };
+    }
+    return undefined;
+}
+function validateOptionalNumberObject(record, key, allowed, required) {
+    if (record[key] === undefined)
+        return undefined;
+    return validateObjectNumbers(record[key], allowed, required, `metrics.${key}`);
+}
+function validateMetrics(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, reason: "metrics must be an object" };
+    }
+    const metrics = value;
+    if (!keysAllowed(metrics, ALLOWED_METRICS_KEYS)) {
+        return { ok: false, reason: "metrics has unknown keys" };
+    }
+    const required = validateRequiredNumbers(metrics, REQUIRED_METRIC_KEYS, "metrics");
+    if (required !== undefined)
+        return required;
+    const aug = validateObjectNumbers(metrics.augmentation, ALLOWED_AUGMENTATION_KEYS, ["deterministic", "modelAugmented", "modelAugmentedShare"], "metrics.augmentation");
+    if (aug !== undefined)
+        return aug;
+    return (validateOptionalNumberObject(metrics, "navGraph", ALLOWED_NAV_GRAPH_KEYS, [
+        "screens",
+        "transitions",
+    ]) ?? validateOptionalNumberObject(metrics, "a11y", ALLOWED_A11Y_KEYS, ["findings"]));
+}
+function validateScreenCollections(record) {
+    if (!Array.isArray(record.screens) || !Array.isArray(record.skippedScreens)) {
+        return { ok: false, reason: "screens and skippedScreens must be arrays" };
+    }
+    if (record.structuralScreens !== undefined && !Array.isArray(record.structuralScreens)) {
+        return { ok: false, reason: "structuralScreens must be an array" };
+    }
+    return undefined;
+}
+// Strict-schema gate for a deserialised snapshot record: schema-version literal + closed key set.
+// Structural correctness of the integrity hashes is the builder's responsibility, not this gate's.
+export function validateFigmaSnapshotRecord(value) {
+    if (typeof value !== "object" || value === null) {
+        return { ok: false, reason: "record is not an object" };
+    }
+    const record = value;
+    if (record.figmaSnapshotSchemaVersion !== FIGMA_SNAPSHOT_SCHEMA_VERSION) {
+        return {
+            ok: false,
+            reason: `unexpected figmaSnapshotSchemaVersion (expected ${String(FIGMA_SNAPSHOT_SCHEMA_VERSION)})`,
+        };
+    }
+    for (const key of Object.keys(record)) {
+        if (!ALLOWED_TOP_LEVEL_KEYS.has(key)) {
+            return { ok: false, reason: `unknown record key: ${key}` };
+        }
+    }
+    const screenCollectionsValidation = validateScreenCollections(record);
+    if (screenCollectionsValidation !== undefined)
+        return screenCollectionsValidation;
+    const artifactHashesValidation = validateArtifactHashes(record.artifactHashes);
+    if (artifactHashesValidation !== undefined)
+        return artifactHashesValidation;
+    const metricsValidation = validateMetrics(record.metrics);
+    if (metricsValidation !== undefined)
+        return metricsValidation;
+    return { ok: true, reason: undefined };
+}

package/dist/qualityIntelligence/figmaSnapshot/store.d.ts

@@ -0,0 +1,144 @@
+import { type WorkspaceFs } from "@oscharko-dev/keiko-workspace";
+import { type FigmaSnapshotImageRef, type FigmaSnapshotLinkRow, type FigmaSnapshotMetrics, type FigmaSnapshotRecord } from "./schema.js";
+export interface RecordFigmaSnapshotScreenInput {
+    readonly screenId: string;
+    readonly irJson: unknown;
+    readonly integrityHash: string;
+    readonly image: {
+        readonly mimeType: "image/png";
+        readonly bytes: Uint8Array;
+    };
+}
+export interface RecordFigmaSnapshotStructuralScreenInput {
+    readonly screenId: string;
+    readonly reason: string;
+    readonly irJson: unknown;
+    readonly integrityHash: string;
+}
+export interface RecordFigmaSnapshotInput {
+    readonly runId: string;
+    readonly provenance: {
+        readonly fileKey: string;
+        readonly nodeId: string;
+        readonly version: string | undefined;
+        readonly fetchedAt: string;
+    };
+    readonly integrityHash: string;
+    readonly screens: readonly RecordFigmaSnapshotScreenInput[];
+    /** Structural Screen-IR for skipped/non-rendered screens. Optional for callers predating this. */
+    readonly structuralScreens?: readonly RecordFigmaSnapshotStructuralScreenInput[];
+    readonly skippedScreens: readonly {
+        readonly screenId: string;
+        readonly reason: string;
+    }[];
+    /** Raw inter-screen transitions for the navigation/flow graph (#811). Optional + additive. */
+    readonly links?: readonly FigmaSnapshotLinkRow[];
+    /** Deterministic design-tokens artifact (#752), opaque, for design-to-code (#755). Optional. */
+    readonly tokens?: unknown;
+    /** Numeric operational metrics (#760). Optional for older snapshots. */
+    readonly metrics?: FigmaSnapshotMetrics;
+}
+export interface RecordFigmaSnapshotResult {
+    readonly recordPath: string;
+    readonly sideFileDir: string;
+}
+/** Summary entry returned by {@link FigmaSnapshotStore.listByScope}. */
+export interface FigmaSnapshotScopeEntry {
+    readonly runId: string;
+    readonly fetchedAt: string;
+    readonly integrityHash: string;
+}
+/**
+ * Mutable operator-facing management metadata for a write-once snapshot record.
+ *
+ * Stored separately from `<runId>.figma-snapshot.json` so a human rename never mutates the
+ * immutable evidence artifact or its integrity hash graph.
+ */
+export interface FigmaSnapshotUserMetadata {
+    readonly displayName?: string;
+    readonly updatedAt: string;
+}
+export interface UpdateFigmaSnapshotUserMetadataInput {
+    /** Empty string or null clears the display name. */
+    readonly displayName?: string | null | undefined;
+    /** Injectable for tests and audited routes; defaults to the current time. */
+    readonly updatedAt?: string | undefined;
+}
+export interface DeleteFigmaSnapshotResult {
+    readonly runId: string;
+    readonly recordDeleted: boolean;
+    readonly sideFileDirDeleted: boolean;
+    readonly metadataDeleted: boolean;
+}
+export interface FigmaSnapshotImageBytes {
+    readonly mimeType: "image/png";
+    readonly bytes: Uint8Array;
+    readonly sha256: string;
+    readonly byteLength: number;
+}
+export interface FigmaSnapshotStore {
+    readonly record: (input: RecordFigmaSnapshotInput) => RecordFigmaSnapshotResult;
+    readonly load: (runId: string) => FigmaSnapshotRecord | undefined;
+    /**
+     * Loads and verifies the JSON snapshot record and hash graph without reading every image side-file.
+     * Callers that stream one image must then verify that requested side-file with loadImage().
+     */
+    readonly loadMetadata: (runId: string) => FigmaSnapshotRecord | undefined;
+    readonly loadImage: (runId: string, image: FigmaSnapshotImageRef) => FigmaSnapshotImageBytes;
+    /** Loads mutable user metadata without touching the immutable evidence record. */
+    readonly loadUserMetadata: (runId: string) => FigmaSnapshotUserMetadata | undefined;
+    /** Upserts mutable user metadata next to the immutable record. */
+    readonly updateUserMetadata: (runId: string, input: UpdateFigmaSnapshotUserMetadataInput) => FigmaSnapshotUserMetadata;
+    /** Deletes the immutable record, rendered side-files, and mutable management metadata together. */
+    readonly deleteSnapshot: (runId: string) => DeleteFigmaSnapshotResult;
+    readonly location: (runId: string) => string;
+    /**
+     * List all snapshot records for a specific Figma scope, sorted by `fetchedAt` descending
+     * (most-recent first). Reads only the record headers — cheap scan. Unparseable files are
+     * skipped silently. Used by drift work (#735) to find existing snapshots for re-comparison.
+     */
+    readonly listByScope: (fileKey: string, nodeId: string) => readonly FigmaSnapshotScopeEntry[];
+    /**
+     * List the most recent snapshot run ids across all scopes, sorted by `fetchedAt` descending.
+     * Reads only the record headers and skips unparseable files silently.
+     */
+    readonly listRecent: (limit?: number) => readonly string[];
+}
+export interface FigmaSnapshotStoreOptions {
+    readonly fs?: WorkspaceFs;
+    readonly randomSuffix?: () => string;
+    /**
+     * Count-based retention applied ONCE per store instance from the lazy sweep seam (Issue #1323
+     * AC4 — make retention operational). Figma snapshot records carry no retention policy id; they
+     * are evicted oldest-first by `fetchedAt` beyond `maxRecords`. Omitted → the conservative default
+     * cap ({@link DEFAULT_FIGMA_SNAPSHOT_MAX_RECORDS}) is used so a normal local set is never silently
+     * purged. A non-positive `maxRecords` disables retention entirely.
+     */
+    readonly retention?: {
+        readonly maxRecords?: number;
+    } | undefined;
+}
+/**
+ * Conservative default Figma-snapshot retention cap. Chosen to match the QI `qi:standard-90d`
+ * profile's `maxRunArtifacts` (500) — the least-destructive value that still bounds growth, so
+ * wiring retention on by default does NOT surprise an operator with an aggressive small cap (ADR-0048).
+ * Deployments raise/lower it via `FigmaSnapshotStoreOptions.retention.maxRecords`.
+ */
+export declare const DEFAULT_FIGMA_SNAPSHOT_MAX_RECORDS = 500;
+export interface FigmaSnapshotRetentionProfile {
+    /** Maximum number of snapshots to keep (newest first by fetchedAt). */
+    readonly maxRecords: number;
+}
+/**
+ * Enforce store-level retention for Figma snapshot records. Deletes the RECORD first, then the
+ * side-file dir, so a partially-retained snapshot is never in a state where the record is gone
+ * but the side-files remain (the side-files are unreachable without the record). A retained
+ * record's side-dir is never touched.
+ *
+ * Wiring: call this alongside `deleteQualityIntelligenceRun` in the QI retention orchestrator
+ * (#274). The profiles are intentionally separate because snapshot retention may differ from
+ * run-manifest retention (snapshots are larger, longer-lived evidence artifacts).
+ */
+export declare function enforceFigmaSnapshotRetention(evidenceDir: string, profile: FigmaSnapshotRetentionProfile): void;
+export declare function createNodeFigmaSnapshotStore(evidenceDir: string, options?: FigmaSnapshotStoreOptions): FigmaSnapshotStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/qualityIntelligence/figmaSnapshot/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figmaSnapshot/store.ts"],"names":[],"mappings":"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"}