my-frontend-observer 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.4.0 - 2026-08-12
+
+Layout Relationships, Dependency Evidence, and Before/After Comparison.
+
+- New comparison artifact kind `my-frontend-observer/comparison`, schema
+  `1.0.0` - independent of and never reused for the observation schema.
+- Canonical layout-relationship derivation from a single observation:
+  horizontal order (`left-of`/`right-of`/`horizontally-overlapping`),
+  vertical order (`above`/`below`/`vertically-overlapping`), area overlap,
+  relative width, geometric fit (kept explicitly distinct from DOM
+  containment), vertical sequencing (`follows-vertically`), and document-
+  width fit/exceeds-viewport - bounded to configured targets, with explicit
+  evidence-path provenance and honest unresolved-target handling.
+- Comparability analysis, evaluated before any rendered difference:
+  `comparable` / `comparable-with-warnings` / `incomparable`, with
+  structured reasons (hard mismatches on page URL, viewport, browser
+  engine, or scroll-scenario configuration; warnings for producer/browser
+  version and target-configuration differences; theme/authenticated-state/
+  application-state recorded as unassessed, never silently equal).
+- Before/after target and page differences: appeared/disappeared (never
+  confused with a target added/removed from configuration), moved, resized,
+  visibility changes, clipping changes (reusing one canonical clipping
+  derivation), actual horizontal/vertical dimensional-overflow changes, DOM
+  containment changes, page-size changes, and scroll-owner changes - each a
+  structured record with before/after values, deltas where meaningful, and
+  supporting evidence references.
+- Relationship-change detection between two observations, matched by
+  relationship family and subject/related target (never array position),
+  including a `relative-position-changed` distinction from plain absolute
+  target movement.
+- Explicit, non-causal expected-dependency evidence: a caller may declare an
+  expected relationship between two targets' `x`/`y`/`width`/`height`
+  properties and `increase`/`decrease`/`change`/`unchanged` directions; each
+  declaration evaluates independently to `consistent` / `not-observed` /
+  `contradictory-to-declaration` / `unavailable`. The observer never infers
+  a dependency from observed co-change and never produces a causal claim.
+- Deterministic, direction-sensitive comparison identity
+  (`comparisonRequestId`) plus a fresh `comparisonId` per execution;
+  operational filesystem paths never affect identity and are never written
+  into the persisted manifest.
+- Atomic comparison-artifact persistence: `<outputLocation>/<comparisonId>/
+  manifest.json` only - no screenshot bytes are copied; the manifest
+  retains logical references to the source observations' own
+  `screenshot.path`. Source observations are never modified.
+- New public `compare` command: `my-frontend-observer compare --before
+  <observation-artifact-root> --after <observation-artifact-root> --output
+  <directory> [--config-file <json-file>]`. Reads two already-persisted
+  observation artifacts and never launches a browser. `comparable`,
+  `comparable-with-warnings`, and `incomparable` all persist successfully
+  and exit `0`; only invalid syntax, an unreadable/invalid source artifact,
+  invalid configuration, or a failed write exits nonzero.
+
 ## 0.3.0 - 2026-08-12
 
 Runtime Scrolling, Overflow, and Visibility Behavior.

package/README.md

@@ -6,12 +6,15 @@ in [docs/PROJECT_DESCRIPTION.md](docs/PROJECT_DESCRIPTION.md).
 
 ## Current status
 
-`v0.3.0`, Runtime Scrolling, Overflow, and Visibility Behavior, is the
-current published release: `my-frontend-observer observe` launches a real,
-sandboxed Chromium browser, enforces a loopback-only safety policy,
-captures a viewport screenshot plus bounded page/target evidence, and
-persists it as one portable `manifest.json` + `screenshot.png` artifact
-(observation schema `1.2.0`).
+`v0.4.0`, Layout Relationships, Dependency Evidence, and Before/After
+Comparison, is the current published release: `my-frontend-observer observe`
+launches a real, sandboxed Chromium browser, enforces a loopback-only safety
+policy, captures a viewport screenshot plus bounded page/target evidence,
+and persists it as one portable `manifest.json` + `screenshot.png` artifact
+(observation schema `1.2.0`). `my-frontend-observer compare` reads two
+already-persisted observation artifacts and derives before/after evidence
+purely from their existing content, persisting a comparison artifact
+(comparison schema `1.0.0`).
 
 Install:
 
@@ -67,6 +70,27 @@ in
 [docs/COMMANDS.md](docs/COMMANDS.md#scroll-scenario---scroll-scenario-file)
 for the exact JSON format and flag reference.
 
+### Comparison
+
+`my-frontend-observer compare` reads two already-persisted observation
+artifacts and derives before/after evidence purely from their existing
+content - it never launches a browser:
+
+```powershell
+my-frontend-observer compare `
+  --before observations/<before-observation-id> `
+  --after observations/<after-observation-id> `
+  --output comparisons
+```
+
+(From a source checkout, use `node dist/cli.js compare ...` instead.)
+
+This prints a concise result (`Comparison:`/`State:`/`Artifact:`/
+`Differences:`/`Relationship changes:`/`Diagnostics:`) and exits `0` -
+including when the two observations turn out to be `incomparable`, which is
+itself a successful comparison outcome. See
+[docs/COMMANDS.md](docs/COMMANDS.md) for the full flag reference.
+
 Validation:
 
 ```powershell
@@ -84,8 +108,8 @@ Planning authorities:
   intent and responsibility boundaries.
 - [Project Milestones](docs/PROJECT_MILESTONES.md): complete ordered capability
   design and cross-milestone rules.
-- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1, v0.2, and
-  v0.3 are released, v0.4 is next.
+- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1-v0.4 are
+  released, v0.5 is next.
 - [Current State](docs/CURRENT_STATE.md): retained scaffold and release state.
 
 No sibling ecosystem repository is a runtime dependency of the retained

package/dist/application/comparisonService.d.ts

@@ -0,0 +1,56 @@
+import type { ObservationArtifact } from '../domain/schema.js';
+import type { ComparabilityState, ComparisonConfig } from '../domain/comparison.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { WriteComparisonArtifactOptions } from '../artifacts/comparisonArtifactWriter.js';
+export type { PersistedComparisonResult } from '../artifacts/comparisonArtifactWriter.js';
+/** Default comparison output location, mirroring `request.ts`'s `DEFAULT_OUTPUT_LOCATION` for observations - distinct directories so comparisons never collide with source observations. */
+export declare const DEFAULT_COMPARISON_OUTPUT_LOCATION = "comparisons";
+export interface CompareAndPersistOptions {
+    config?: Partial<ComparisonConfig>;
+    /** Portable, relative output location (validated the same way as an observation's `outputLocation`). Defaults to `DEFAULT_COMPARISON_OUTPUT_LOCATION`. */
+    outputLocation?: string;
+    cwd?: WriteComparisonArtifactOptions['cwd'];
+}
+/**
+ * Observer-owned summary of one full compare-and-persist attempt, with just
+ * enough information for a presentation layer (a future Batch 4 CLI) to
+ * report a result without seeing a raw filesystem exception or persistence
+ * implementation detail.
+ */
+export type ApplicationComparisonResult = {
+    ok: true;
+    comparisonId: string;
+    comparisonRequestId: string;
+    comparability: ComparabilityState;
+    artifactRoot: string;
+    manifestPath: string;
+    differenceCount: number;
+    relationshipChangeCount: number;
+    diagnosticsCount: number;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * The one canonical application-level comparison use case: takes two
+ * already-validated/in-memory `ObservationArtifact`s, runs the existing pure
+ * `compareObservations` exactly once, and - only for a structurally valid
+ * result - persists it exactly once through the existing comparison
+ * writer. Never launches Chromium, never re-resolves targets, never mutates
+ * either source observation.
+ */
+export declare function compareAndPersist(before: ObservationArtifact, after: ObservationArtifact, options?: CompareAndPersistOptions): Promise<ApplicationComparisonResult>;
+/**
+ * The canonical Batch 4 CLI-facing orchestration: reads two already-persisted
+ * observation artifacts by their root directory (each expected to contain
+ * `manifest.json`, mirroring `writeObservationArtifact`'s own layout) through
+ * the existing `readObservationArtifact` reader, then delegates to
+ * `compareAndPersist` exactly once. A thin wrapper only - artifact reading
+ * stays owned by `artifacts/artifactReader.ts`, comparison stays owned by
+ * `domain/comparisonEngine.ts`, and persistence stays owned by
+ * `artifacts/comparisonArtifactWriter.ts`. Kept in `application/` (not
+ * `artifacts/`) so `src/cli.ts` can depend on it without importing the
+ * artifacts layer directly - see `tests/unit/cli.test.ts`'s import-boundary
+ * assertion. Never launches a browser, never re-resolves targets.
+ */
+export declare function compareAndPersistFromArtifactRoots(beforeRoot: string, afterRoot: string, options?: CompareAndPersistOptions): Promise<ApplicationComparisonResult>;

package/dist/application/comparisonService.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import { compareObservations } from '../domain/comparisonEngine.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+import { normalizeOutputLocation } from '../request/paths.js';
+import { writeComparisonArtifact } from '../artifacts/comparisonArtifactWriter.js';
+import { readObservationArtifact } from '../artifacts/artifactReader.js';
+import { MANIFEST_FILENAME as OBSERVATION_MANIFEST_FILENAME } from '../artifacts/artifactWriter.js';
+/** Default comparison output location, mirroring `request.ts`'s `DEFAULT_OUTPUT_LOCATION` for observations - distinct directories so comparisons never collide with source observations. */
+export const DEFAULT_COMPARISON_OUTPUT_LOCATION = 'comparisons';
+/**
+ * The one canonical application-level comparison use case: takes two
+ * already-validated/in-memory `ObservationArtifact`s, runs the existing pure
+ * `compareObservations` exactly once, and - only for a structurally valid
+ * result - persists it exactly once through the existing comparison
+ * writer. Never launches Chromium, never re-resolves targets, never mutates
+ * either source observation.
+ */
+export async function compareAndPersist(before, after, options = {}) {
+    const result = compareObservations(before, after, options.config ?? {});
+    if (!result.ok) {
+        return {
+            ok: false,
+            diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message: result.reason }],
+        };
+    }
+    const rawOutputLocation = options.outputLocation ?? DEFAULT_COMPARISON_OUTPUT_LOCATION;
+    const normalized = normalizeOutputLocation(rawOutputLocation);
+    if (!normalized.ok) {
+        return { ok: false, diagnostics: [normalized.diagnostic] };
+    }
+    const persisted = await writeComparisonArtifact(result.artifact, normalized.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok) {
+        return { ok: false, diagnostics: persisted.diagnostics };
+    }
+    return {
+        ok: true,
+        comparisonId: result.artifact.comparisonId,
+        comparisonRequestId: result.artifact.comparisonRequestId,
+        comparability: result.artifact.comparability.state,
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        differenceCount: result.artifact.differences.length,
+        relationshipChangeCount: result.artifact.relationshipChanges.length,
+        diagnosticsCount: result.artifact.diagnostics.length,
+    };
+}
+/**
+ * The canonical Batch 4 CLI-facing orchestration: reads two already-persisted
+ * observation artifacts by their root directory (each expected to contain
+ * `manifest.json`, mirroring `writeObservationArtifact`'s own layout) through
+ * the existing `readObservationArtifact` reader, then delegates to
+ * `compareAndPersist` exactly once. A thin wrapper only - artifact reading
+ * stays owned by `artifacts/artifactReader.ts`, comparison stays owned by
+ * `domain/comparisonEngine.ts`, and persistence stays owned by
+ * `artifacts/comparisonArtifactWriter.ts`. Kept in `application/` (not
+ * `artifacts/`) so `src/cli.ts` can depend on it without importing the
+ * artifacts layer directly - see `tests/unit/cli.test.ts`'s import-boundary
+ * assertion. Never launches a browser, never re-resolves targets.
+ */
+export async function compareAndPersistFromArtifactRoots(beforeRoot, afterRoot, options = {}) {
+    const beforeRead = await readObservationArtifact(path.join(beforeRoot, OBSERVATION_MANIFEST_FILENAME));
+    if (!beforeRead.ok) {
+        return {
+            ok: false,
+            diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message: `--before observation artifact: ${beforeRead.reason}` }],
+        };
+    }
+    const afterRead = await readObservationArtifact(path.join(afterRoot, OBSERVATION_MANIFEST_FILENAME));
+    if (!afterRead.ok) {
+        return {
+            ok: false,
+            diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message: `--after observation artifact: ${afterRead.reason}` }],
+        };
+    }
+    return compareAndPersist(beforeRead.artifact, afterRead.artifact, options);
+}
+//# sourceMappingURL=comparisonService.js.map

package/dist/application/comparisonService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparisonService.js","sourceRoot":"","sources":["../../src/application/comparisonService.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAC;AAEnF,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,iBAAiB,IAAI,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAIpG,4LAA4L;AAC5L,MAAM,CAAC,MAAM,kCAAkC,GAAG,aAAa,CAAC;AAgChE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAA2B,EAC3B,KAA0B,EAC1B,UAAoC,EAAE;IAEtC,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IACxE,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO;YACL,EAAE,EAAE,KAAK;YACT,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;SACrH,CAAC;IACJ,CAAC;IAED,MAAM,iBAAiB,GAAG,OAAO,CAAC,cAAc,IAAI,kCAAkC,CAAC;IACvF,MAAM,UAAU,GAAG,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;IAC9D,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;QACnB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;IAC7D,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,uBAAuB,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1I,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;QAClB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,CAAC,WAAW,EAAE,CAAC;IAC3D,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,YAAY;QAC1C,mBAAmB,EAAE,MAAM,CAAC,QAAQ,CAAC,mBAAmB;QACxD,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK;QAClD,YAAY,EAAE,SAAS,CAAC,YAAY;QACpC,YAAY,EAAE,SAAS,CAAC,YAAY;QACpC,eAAe,EAAE,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,MAAM;QACnD,uBAAuB,EAAE,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,MAAM;QACnE,gBAAgB,EAAE,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,MAAM;KACrD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,kCAAkC,CACtD,UAAkB,EAClB,SAAiB,EACjB,UAAoC,EAAE;IAEtC,MAAM,UAAU,GAAG,MAAM,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,6BAA6B,CAAC,CAAC,CAAC;IACvG,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;QACnB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,kCAAkC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;SAC7J,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,6BAA6B,CAAC,CAAC,CAAC;IACrG,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;QAClB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,iCAAiC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;SAC3J,CAAC;IACJ,CAAC;IAED,OAAO,iBAAiB,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC7E,CAAC"}

package/dist/artifacts/artifactReader.d.ts

@@ -0,0 +1,19 @@
+import type { ObservationArtifact } from '../domain/schema.js';
+export type ReadObservationArtifactResult = {
+    ok: true;
+    artifact: ObservationArtifact;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Narrow canonical reader counterpart to `artifactWriter.ts#writeObservationArtifact`:
+ * reads one `manifest.json`, parses it, and validates it through the same
+ * `isValidObservationArtifact` structural gate the writer itself uses -
+ * never a second validator. Read-only: never mutates the file, never
+ * launches a browser, never resolves the sibling screenshot's bytes (the
+ * manifest's `screenshot.path` field is returned as-is for the caller to
+ * resolve if it needs to). Established here as the canonical reader ahead of
+ * the Batch 4 `compare` CLI's `--before`/`--after` path arguments.
+ */
+export declare function readObservationArtifact(manifestPath: string): Promise<ReadObservationArtifactResult>;

package/dist/artifacts/artifactReader.js

@@ -0,0 +1,36 @@
+import { readFile } from 'node:fs/promises';
+import { isValidObservationArtifact } from '../domain/schema.js';
+/**
+ * Narrow canonical reader counterpart to `artifactWriter.ts#writeObservationArtifact`:
+ * reads one `manifest.json`, parses it, and validates it through the same
+ * `isValidObservationArtifact` structural gate the writer itself uses -
+ * never a second validator. Read-only: never mutates the file, never
+ * launches a browser, never resolves the sibling screenshot's bytes (the
+ * manifest's `screenshot.path` field is returned as-is for the caller to
+ * resolve if it needs to). Established here as the canonical reader ahead of
+ * the Batch 4 `compare` CLI's `--before`/`--after` path arguments.
+ */
+export async function readObservationArtifact(manifestPath) {
+    let raw;
+    try {
+        raw = await readFile(manifestPath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `failed to read observation artifact manifest at "${manifestPath}": ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `observation artifact manifest at "${manifestPath}" is not valid JSON: ${message}` };
+    }
+    const validation = isValidObservationArtifact(parsed);
+    if (!validation.valid) {
+        return { ok: false, reason: `observation artifact manifest at "${manifestPath}" failed structural validation: ${validation.reason}` };
+    }
+    return { ok: true, artifact: parsed };
+}
+//# sourceMappingURL=artifactReader.js.map

package/dist/artifacts/artifactReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactReader.js","sourceRoot":"","sources":["../../src/artifacts/artifactReader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAIjE;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,YAAoB;IAChE,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oDAAoD,YAAY,MAAM,OAAO,EAAE,EAAE,CAAC;IAChH,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qCAAqC,YAAY,wBAAwB,OAAO,EAAE,EAAE,CAAC;IACnH,CAAC;IAED,MAAM,UAAU,GAAG,0BAA0B,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qCAAqC,YAAY,mCAAmC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;IACxI,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAA6B,EAAE,CAAC;AAC/D,CAAC"}

package/dist/artifacts/comparisonArtifactWriter.d.ts

@@ -0,0 +1,41 @@
+import type { ComparisonArtifact } from '../domain/comparison.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+export declare const COMPARISON_MANIFEST_FILENAME = "manifest.json";
+/**
+ * Observer-owned result of persisting one ComparisonArtifact. Mirrors
+ * `PersistedObservationResult`'s shape/semantics but is its own type: a
+ * comparison directory has no screenshot file, and this writer never touches
+ * `src/artifacts/artifactWriter.ts` or its observation-persistence
+ * guarantees.
+ */
+export type PersistedComparisonResult = {
+    ok: true;
+    artifactRoot: string;
+    manifestPath: string;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+export interface WriteComparisonArtifactOptions {
+    /** Base directory that `outputLocation` is resolved against. Defaults to `process.cwd()`. */
+    cwd?: string;
+}
+/**
+ * Persists one already-assembled, already-validated `ComparisonArtifact` as
+ * one portable artifact directory: `<outputLocation>/<comparisonId>/manifest.json`
+ * only - no screenshot is copied (the manifest's `before`/`after.screenshot`
+ * fields already point back to the source observations; see
+ * `domain/comparisonEngine.ts#sourceReference`), and no `relationships.json`/
+ * `differences.json`/`diff.png` side files are produced.
+ *
+ * Follows the same atomic-write discipline as
+ * `artifacts/artifactWriter.ts#writeObservationArtifact` (sibling temporary
+ * directory, then one atomic rename onto the final name) without sharing its
+ * implementation - a comparison directory has a different, smaller content
+ * shape, and this function never touches observation persistence. A fresh
+ * `comparisonId` per execution normally prevents collisions; an existing
+ * directory at the final path is treated as a genuine collision and
+ * rejected rather than overwritten, so prior comparison evidence is never
+ * destructively replaced.
+ */
+export declare function writeComparisonArtifact(artifact: ComparisonArtifact, outputLocation: string, options?: WriteComparisonArtifactOptions): Promise<PersistedComparisonResult>;

package/dist/artifacts/comparisonArtifactWriter.js

@@ -0,0 +1,67 @@
+import { mkdir, writeFile, rename, rm, access } from 'node:fs/promises';
+import path from 'node:path';
+import { isValidComparisonArtifact } from '../domain/comparison.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+export const COMPARISON_MANIFEST_FILENAME = 'manifest.json';
+function writeFailure(message, details) {
+    const diagnostic = {
+        code: 'artifact-write-failure',
+        severity: DIAGNOSTIC_SEVERITY['artifact-write-failure'],
+        message,
+        ...(details === undefined ? {} : { details }),
+    };
+    return { ok: false, diagnostics: [diagnostic] };
+}
+async function pathExists(candidate) {
+    return access(candidate).then(() => true, () => false);
+}
+/**
+ * Persists one already-assembled, already-validated `ComparisonArtifact` as
+ * one portable artifact directory: `<outputLocation>/<comparisonId>/manifest.json`
+ * only - no screenshot is copied (the manifest's `before`/`after.screenshot`
+ * fields already point back to the source observations; see
+ * `domain/comparisonEngine.ts#sourceReference`), and no `relationships.json`/
+ * `differences.json`/`diff.png` side files are produced.
+ *
+ * Follows the same atomic-write discipline as
+ * `artifacts/artifactWriter.ts#writeObservationArtifact` (sibling temporary
+ * directory, then one atomic rename onto the final name) without sharing its
+ * implementation - a comparison directory has a different, smaller content
+ * shape, and this function never touches observation persistence. A fresh
+ * `comparisonId` per execution normally prevents collisions; an existing
+ * directory at the final path is treated as a genuine collision and
+ * rejected rather than overwritten, so prior comparison evidence is never
+ * destructively replaced.
+ */
+export async function writeComparisonArtifact(artifact, outputLocation, options = {}) {
+    const validation = isValidComparisonArtifact(artifact);
+    if (!validation.valid) {
+        return writeFailure(`refusing to persist an invalid ComparisonArtifact: ${validation.reason}`);
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const outputRoot = path.resolve(cwd, outputLocation);
+    const finalRoot = path.join(outputRoot, artifact.comparisonId);
+    const tempRoot = path.join(outputRoot, `.tmp-${artifact.comparisonId}`);
+    if (await pathExists(finalRoot)) {
+        return writeFailure(`a comparison artifact already exists at "${artifact.comparisonId}"; refusing to overwrite it`, {
+            artifactRoot: finalRoot,
+        });
+    }
+    try {
+        await rm(tempRoot, { recursive: true, force: true });
+        await mkdir(tempRoot, { recursive: true });
+        await writeFile(path.join(tempRoot, COMPARISON_MANIFEST_FILENAME), JSON.stringify(artifact, null, 2), 'utf8');
+        await rename(tempRoot, finalRoot);
+        return {
+            ok: true,
+            artifactRoot: finalRoot,
+            manifestPath: path.join(finalRoot, COMPARISON_MANIFEST_FILENAME),
+        };
+    }
+    catch (err) {
+        await rm(tempRoot, { recursive: true, force: true }).catch(() => undefined);
+        const message = err instanceof Error ? err.message : String(err);
+        return writeFailure(`failed to persist comparison artifact: ${message}`);
+    }
+}
+//# sourceMappingURL=comparisonArtifactWriter.js.map

package/dist/artifacts/comparisonArtifactWriter.js.map

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