@bytebrand/export-cars 1.26.38 → 1.26.40

package/src/services/criteo-feed-run.ts

@@ -0,0 +1,253 @@
+import { promises as fs } from 'fs';
+import { dirname, join } from 'path';
+import { get, toNumber, toString } from 'lodash';
+import { ImboImageResponseInterface } from '@bytebrand/chunkable';
+import { DataSchemes } from '@bytebrand/car-schema';
+
+import { GoogleXmlBuilder } from '../formats/google-xml.builder';
+import { CriteoXmlItem } from '../interfaces';
+import { FeedGuard, FeedGuardError, LastGood, inspectSourceSnapshot } from './feed-guard';
+
+export interface CriteoSourceCar {
+  car: DataSchemes.Car;
+  images: ImboImageResponseInterface[];
+}
+
+export enum CriteoExclusion {
+  noId = 'no_id',
+  duplicateId = 'duplicate_id',
+  filtered = 'filtered',
+  notAvailable = 'reserved_or_sold',
+  noPrice = 'no_valid_price',
+  noImage = 'no_marketing_image',
+}
+
+// Online cars flagged like this are not sellable stock (same rule as the AutoUncle feed). Criteo
+// (16.10.2026): only currently marketable stock goes into the full file; a car that leaves it is
+// removed by the next full import.
+const NOT_AVAILABLE = ['selector_offerAvailability_reserved', 'selector_offerAvailability_sold'];
+
+// Everything the run needs from the outside world — the Nest exporter wires the real services,
+// tests pass fakes.
+export interface CriteoRunDeps {
+  // iterates the base export snapshot chunk by chunk (LoaderService.process)
+  forEachChunk: (fn: (cars: CriteoSourceCar[]) => Promise<void>) => Promise<unknown>;
+  // existing shared partner filter (images count, Cronicle rules)
+  filterCar: (source: CriteoSourceCar) => boolean;
+  // CriteoTransformer.transform: null = no real marketing image
+  transform: (source: CriteoSourceCar) => Promise<CriteoXmlItem | null>;
+  guard: FeedGuard;
+}
+
+export interface CriteoRunOptions {
+  runId?: string;
+  domain: string;
+  sourceDirectory: string;
+  sourceBaseFileName: string;
+  xmlFile: string;
+  stateDir: string;
+  now?: () => Date;
+}
+
+export interface CriteoRunReport {
+  runId?: string;
+  startedAt: string;
+  finishedAt?: string;
+  durationMs?: number;
+  status: 'published' | 'blocked' | 'failed';
+  guard?: { code: string; message: string };
+  error?: string;
+  xmlFile: string;
+  source: { files: number; newestChunkAt: string | null; ageHours: number | null; cars: number };
+  items: number;
+  excluded: Record<string, number>;
+  withRate: number;
+  withoutEnergyClass: number;
+  // against the ids of the last published file; removed ids are dropped by Criteo's next full import
+  ids: { added: number; removed: number; kept: number; removedSample: string[] } | null;
+  lastGood: LastGood | null;
+  lastGoodAgeHours: number | null;
+  stale: boolean;
+}
+
+const HOUR_MS = 60 * 60 * 1000;
+const PRICE = /^\d+(\.\d+)? EUR$/;
+
+const increment = (counter: Record<string, number>, key: string) => {
+  counter[key] = (counter[key] ?? 0) + 1;
+};
+
+/**
+ * One Criteo catalog run (ADV-319): source check -> map -> temp XML -> count check -> atomic
+ * publish -> report. Nothing outside the output directory and `stateDir` is written. A blocked run
+ * leaves the last good XML in place and fails the job, so the chained upload step does not run.
+ * The XML format, enums and field order stay the legacy Criteo ones.
+ */
+export class CriteoFeedRun {
+  constructor(private readonly deps: CriteoRunDeps, private readonly options: CriteoRunOptions) { }
+
+  private now(): Date {
+    return this.options.now ? this.options.now() : new Date();
+  }
+
+  private get idsFile(): string {
+    return join(this.options.stateDir, 'published-ids.json');
+  }
+
+  async run(): Promise<CriteoRunReport> {
+    const { guard } = this.deps;
+    const { xmlFile, runId } = this.options;
+    const startedAt = this.now();
+    const lastGood = await guard.readLastGood();
+    const report: CriteoRunReport = {
+      runId,
+      startedAt: startedAt.toISOString(),
+      status: 'failed',
+      xmlFile,
+      source: { files: 0, newestChunkAt: null, ageHours: null, cars: 0 },
+      items: 0,
+      excluded: {},
+      withRate: 0,
+      withoutEnergyClass: 0,
+      ids: null,
+      lastGood,
+      lastGoodAgeHours: guard.staleHours(lastGood, startedAt),
+      stale: guard.isStale(lastGood, startedAt),
+    };
+
+    await guard.acquireLock(runId ?? 'local', startedAt);
+    const tmpFile = `${xmlFile}.tmp`;
+    try {
+      const snapshot = await inspectSourceSnapshot(this.options.sourceDirectory, this.options.sourceBaseFileName);
+      report.source.files = snapshot.files;
+      report.source.newestChunkAt = snapshot.newestMtime?.toISOString() ?? null;
+      report.source.ageHours = snapshot.newestMtime
+        ? Number(((startedAt.getTime() - snapshot.newestMtime.getTime()) / HOUR_MS).toFixed(2))
+        : null;
+      guard.checkSource(snapshot, startedAt);
+
+      await fs.mkdir(dirname(xmlFile), { recursive: true });
+      // the builder appends — never onto a leftover temp file
+      await fs.rm(tmpFile, { force: true });
+      const builder = new GoogleXmlBuilder(tmpFile);
+      await builder.buildStart(this.options.domain);
+
+      const seen = new Set<string>();
+      const published: string[] = [];
+      await this.deps.forEachChunk(async (cars) => {
+        for (const source of cars) {
+          report.source.cars += 1;
+          const reason = this.exclusion(source, seen);
+          if (reason) {
+            increment(report.excluded, reason);
+            continue;
+          }
+          const item = await this.deps.transform(source);
+          if (!item) {
+            increment(report.excluded, CriteoExclusion.noImage);
+            continue;
+          }
+          // the transformer formats the price; a value it could not format is not sent
+          if (!PRICE.test(item.price) || !PRICE.test(item.sale_price)) {
+            increment(report.excluded, CriteoExclusion.noPrice);
+            continue;
+          }
+          await builder.addItem(item);
+          published.push(item.id);
+          report.items += 1;
+          if (item.installment) {
+            report.withRate += 1;
+          }
+          if (!item.energy_efficiency_class) {
+            report.withoutEnergyClass += 1;
+          }
+        }
+      });
+      await builder.buildEnd();
+
+      const counts = { sourceItems: report.source.cars, publishedItems: report.items };
+      guard.checkCounts(counts, lastGood);
+
+      const previousIds = await this.readPublishedIds();
+      report.lastGood = await guard.publish(tmpFile, xmlFile, counts, this.now(), runId);
+      await this.writePublishedIds(published);
+      report.ids = this.diffIds(previousIds, published);
+      report.status = 'published';
+      report.lastGoodAgeHours = 0;
+      report.stale = false;
+      return report;
+    } catch (error) {
+      if (error instanceof FeedGuardError) {
+        report.status = 'blocked';
+        report.guard = { code: error.code, message: error.message };
+      } else {
+        report.error = error?.message ?? String(error);
+      }
+      // keep the rejected file for inspection; the published file stays untouched
+      await fs.rename(tmpFile, `${xmlFile}.rejected`).catch(() => undefined);
+      throw error;
+    } finally {
+      await this.writeReport(report, startedAt);
+      await guard.releaseLock();
+    }
+  }
+
+  private exclusion(source: CriteoSourceCar, seen: Set<string>): CriteoExclusion | null {
+    const id = toString(get(source, 'car._id', ''));
+    if (!id) {
+      return CriteoExclusion.noId;
+    }
+    if (seen.has(id)) {
+      return CriteoExclusion.duplicateId;
+    }
+    seen.add(id);
+    if (!this.deps.filterCar(source)) {
+      return CriteoExclusion.filtered;
+    }
+    if (NOT_AVAILABLE.includes(toString(get(source.car, 'offer.offerAvailability', '')))) {
+      return CriteoExclusion.notAvailable;
+    }
+    const price = toNumber(get(source.car, 'price.currentSalesPrice', null));
+    if (!Number.isFinite(price) || price <= 0) {
+      return CriteoExclusion.noPrice;
+    }
+    return null;
+  }
+
+  private async readPublishedIds(): Promise<string[] | null> {
+    try {
+      return JSON.parse(await fs.readFile(this.idsFile, 'utf8')) as string[];
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  private async writePublishedIds(ids: string[]): Promise<void> {
+    await fs.mkdir(this.options.stateDir, { recursive: true });
+    await fs.writeFile(`${this.idsFile}.tmp`, JSON.stringify(ids), 'utf8');
+    await fs.rename(`${this.idsFile}.tmp`, this.idsFile);
+  }
+
+  private diffIds(previous: string[] | null, current: string[]): CriteoRunReport['ids'] {
+    if (!previous) {
+      return { added: current.length, removed: 0, kept: 0, removedSample: [] };
+    }
+    const before = new Set(previous);
+    const now = new Set(current);
+    const removed = previous.filter(id => !now.has(id));
+    const kept = current.filter(id => before.has(id)).length;
+    return { added: current.length - kept, removed: removed.length, kept, removedSample: removed.slice(0, 20) };
+  }
+
+  private async writeReport(report: CriteoRunReport, startedAt: Date): Promise<void> {
+    const finishedAt = this.now();
+    report.finishedAt = finishedAt.toISOString();
+    report.durationMs = finishedAt.getTime() - startedAt.getTime();
+    await fs.mkdir(this.options.stateDir, { recursive: true });
+    await fs.writeFile(join(this.options.stateDir, 'last-run-report.json'), JSON.stringify(report, null, 2), 'utf8');
+    console.log(`criteo feed report: ${JSON.stringify(report)}`);
+  }
+}

package/src/transformers/criteo.transformer.ts

@@ -1,4 +1,4 @@
-import { escape, get, join, round, toString, trim } from 'lodash';
+import { get, join, round, toString, trim } from 'lodash';
 import { CarDescriptionFactory, DescriptionTypeEnum } from '@bytebrand/car-description';
 import { DataSchemes } from '@bytebrand/car-schema';
 import { TranslatorExtended } from '@bytebrand/schema-tools';
@@ -34,6 +34,11 @@ export class CriteoTransformer {
 			return null;
 		}
 
+		const energyClass = this.getEnergyClass(car);
+		const installment = this.getInstallment(car);
+
+		// Unknown energy class and a missing rate leave their elements out of the item,
+		// instead of sending "default" or a "0 EUR" monthly rate.
 		return {
 			id: carId,
 			title: this.getTitle(car),
@@ -47,17 +52,20 @@ export class CriteoTransformer {
 			brand: get(car, 'mainData.make', ''),
 			price: this.getRetailPrice(car),
 			sale_price: this.getPrice(car),
-			energy_efficiency_class: this.getEnergyClass(car),
+			...(energyClass ? { energy_efficiency_class: energyClass } : {}),
 			color: this.getColor(car),
-			installment: this.getInstallment(car),
-			custom_label_0: `${this.getInstallment(car)} EUR mtl.`,
+			...(installment
+				? { installment, custom_label_0: `${installment.monthlyInstallment} EUR mtl.` }
+				: {}),
 		};
 	}
 
+	// No HTML escaping here: GoogleXmlBuilder escapes every value for XML.
+	// Escaping twice turned "cee'd" into "cee'd".
 	private getTitle(car: DataSchemes.Car): string {
 		const model = toString(get(car, 'mainData.model', ''));
 
-		return trim(escape(join([this.getBrand(car), model], ' ')));
+		return trim(join([this.getBrand(car), model], ' '));
 	}
 
 	private async getDescription(car: DataSchemes.Car): Promise<string> {
@@ -143,16 +151,20 @@ export class CriteoTransformer {
 			selector_energyEfficiencyClass_e: 'E',
 			selector_energyEfficiencyClass_f: 'F',
 			selector_energyEfficiencyClass_g: 'G',
-			selector_unknown: 'default',
 		};
 		// ADV-187: canonical CO2-derived WLTP class, not the unvalidated legacy NEFZ class.
-		const energyClass = get(car, 'environmentEmissions.wltpEnergyEfficiencyClass', 'selector_unknown');
+		// Unknown or unmapped class -> undefined, so the element is left out.
+		const energyClass = get(car, 'environmentEmissions.wltpEnergyEfficiencyClass');
 		return get(available, energyClass);
 	}
 
-	private getInstallment(car: DataSchemes.Car) {
-		const monthlyInstallment = round(get(car, 'rate.monthlyInstallment', null));
-		const paybackPeriod = round(get(car, 'rate.paybackPeriod', null));
+	// A rate is sent only when the car has a real one: both values present and above zero.
+	private getInstallment(car: DataSchemes.Car): CriteoXmlItem['installment'] | undefined {
+		const monthlyInstallment = round(Number(get(car, 'rate.monthlyInstallment')));
+		const paybackPeriod = round(Number(get(car, 'rate.paybackPeriod')));
+		if (!(monthlyInstallment > 0) || !(paybackPeriod > 0)) {
+			return undefined;
+		}
 
 		return {
 			paybackPeriod,

package/test/criteo-feed-run.test.ts

@@ -0,0 +1,365 @@
+// Run: npm test (ts-node, no test framework needed)
+// ADV-319 acceptance: 20 real vehicle cases plus sold / reserved / no image / price change /
+// source outage / duplicate id, and the guard (stale source, count drop, lock, atomic publish).
+// Integration: real files in a temp dir (base export snapshot, output, state), the real
+// CriteoTransformer, GoogleXmlBuilder and FeedGuard; only the marketing image lookup is faked.
+// The 20 cars are anonymized copies of DEV base export cars (05.11.2026): synthetic ids, only the
+// fields the Criteo mapping reads, no dealer data.
+import * as assert from 'node:assert/strict';
+import { promises as fs } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import { FeedGuard, FeedGuardError, FeedGuardOptions } from '../src/services/feed-guard';
+import { CriteoFeedRun, CriteoRunReport, CriteoSourceCar } from '../src/services/criteo-feed-run';
+import { CriteoTransformer } from '../src/transformers/criteo.transformer';
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const REAL_CARS: any[] = require('./fixtures/criteo-20-cases.json');
+
+const NOW = new Date('2026-11-06T08:00:00Z');
+const HOUR = 60 * 60 * 1000;
+const id = (n: number) => `00000000-0000-4000-8000-${String(n).padStart(12, '0')}`;
+const imageUrl = (carId: string) => `https://images.autode-dev.de/generated_images/x/${carId}/criteo-Test.jpg`;
+
+interface World {
+  root: string;
+  source: string;
+  xml: string;
+  state: string;
+  noImage: Set<string>;
+}
+
+const newWorld = async (): Promise<World> => {
+  const root = await fs.mkdtemp(join(tmpdir(), 'criteo-'));
+  return {
+    root,
+    source: join(root, 'cars-export'),
+    xml: join(root, 'criteo-export', 'api_export_cars_criteo.xml'),
+    state: join(root, 'criteo-state'),
+    noImage: new Set(),
+  };
+};
+
+const clone = <T>(value: T): T => JSON.parse(JSON.stringify(value));
+const realSources = (): CriteoSourceCar[] => REAL_CARS.map(car => ({ car: clone(car), images: [] }));
+
+const writeSource = async (world: World, cars: CriteoSourceCar[], { chunkSize = 6, mtime = NOW, skipChunk = -1 } = {}) => {
+  await fs.rm(world.source, { recursive: true, force: true });
+  await fs.mkdir(world.source, { recursive: true });
+  for (let i = 0; i * chunkSize < cars.length; i++) {
+    if (i === skipChunk) {
+      continue;
+    }
+    const file = join(world.source, `cars.${i}.json`);
+    await fs.writeFile(file, JSON.stringify(cars.slice(i * chunkSize, (i + 1) * chunkSize)));
+    await fs.utimes(file, mtime, mtime);
+  }
+};
+
+const guardOptions = (world: World, extra: Partial<FeedGuardOptions> = {}): FeedGuardOptions => ({
+  stateDir: world.state,
+  minSourceItems: 1,
+  minPublishedItems: 1,
+  maxDropPercent: 20,
+  maxSourceAgeHours: 26,
+  maxStaleHours: 48,
+  acceptDrop: false,
+  ...extra,
+});
+
+const run = async (world: World, { at = NOW, guard = {} as Partial<FeedGuardOptions> } = {}): Promise<CriteoRunReport> => {
+  const transformer = new CriteoTransformer(
+    {} as any,
+    { config: { isCriteo: true, imageType: 'marketing', domain: 'autode-dev.de' } } as any,
+    { getImages: async (car: any) => (world.noImage.has(car._id) ? [] : [imageUrl(car._id)]) } as any,
+  );
+  const feedRun = new CriteoFeedRun(
+    {
+      forEachChunk: async (fn) => {
+        const names = (await fs.readdir(world.source)).sort((a, b) => Number(a.split('.')[1]) - Number(b.split('.')[1]));
+        for (const name of names) {
+          await fn(JSON.parse(await fs.readFile(join(world.source, name), 'utf8')));
+        }
+      },
+      filterCar: ({ car }) => (car?.metaData?.imagesCount ?? 0) >= 4,
+      transform: source => transformer.transform(source),
+      guard: new FeedGuard(guardOptions(world, guard)),
+    },
+    {
+      runId: 'test',
+      domain: 'autode-dev.de',
+      sourceDirectory: world.source,
+      sourceBaseFileName: 'cars',
+      xmlFile: world.xml,
+      stateDir: world.state,
+      now: () => at,
+    },
+  );
+  return feedRun.run();
+};
+
+const readReport = async (world: World): Promise<CriteoRunReport> =>
+  JSON.parse(await fs.readFile(join(world.state, 'last-run-report.json'), 'utf8'));
+
+// id -> field -> value of the published XML
+const readItems = async (file: string): Promise<Map<string, Record<string, string>>> => {
+  const xml = await fs.readFile(file, 'utf8');
+  const items = new Map<string, Record<string, string>>();
+  for (const [, body] of xml.matchAll(/<item>([\s\S]*?)<\/item>/g)) {
+    const fields: Record<string, string> = {};
+    for (const [, key, value] of body.matchAll(/<g:(\w+)>([\s\S]*?)<\/g:\1>/g)) {
+      fields[key] = value.replace(/\s+/g, ' ').trim();
+    }
+    items.set(fields.id, fields);
+  }
+  return items;
+};
+
+const exists = (file: string) => fs.access(file).then(() => true, () => false);
+
+const blocked = async (promise: Promise<unknown>, code: string) => {
+  await assert.rejects(promise, (error: any) => error instanceof FeedGuardError && error.code === code);
+};
+
+const tests: Array<[string, () => Promise<void>]> = [
+  ['20 real cars: every car is published once, in source order, with the legacy field order', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources());
+    const report = await run(world);
+    assert.equal(report.status, 'published');
+    assert.equal(report.items, 20);
+    assert.deepEqual(report.excluded, {});
+    const items = await readItems(world.xml);
+    assert.deepEqual([...items.keys()], REAL_CARS.map(car => car._id));
+    const xml = await fs.readFile(world.xml, 'utf8');
+    assert.ok(xml.startsWith('<?xml version="1.0" encoding="UTF-8"?><rss version="2.0" xmlns:g="http://base.google.com/ns/1.0">'));
+    assert.ok(xml.trimEnd().endsWith('</channel></rss>'));
+    assert.ok(!/object Object|>default<|<g:amount>0 EUR|&amp;#|undefined|NaN/.test(xml));
+    const first = xml.match(/<item>([\s\S]*?)<\/item>/)[1];
+    assert.deepEqual([...first.matchAll(/<g:(\w+)>/g)].map(m => m[1]).filter(k => !['months', 'amount'].includes(k)), [
+      'id', 'title', 'description', 'google_product_category', 'product_type', 'link', 'image_link', 'condition',
+      'availability', 'brand', 'price', 'sale_price', 'energy_efficiency_class', 'color', 'installment', 'custom_label_0',
+    ]);
+  }],
+  ['20 real cars: id, link, image, price and condition follow the source car', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources());
+    await run(world);
+    const items = await readItems(world.xml);
+    for (const car of REAL_CARS) {
+      const item = items.get(car._id);
+      assert.equal(item.link, `https://www.autode-dev.de/search/vehicle/${car._id}?source=criteo&amp;medium=cpc&amp;campaign=retargeting`);
+      assert.equal(item.image_link, imageUrl(car._id));
+      assert.equal(item.price, `${car.price.currentSalesPrice} EUR`, car._id);
+      assert.equal(item.sale_price, `${car.price.currentSalesPrice} EUR`, car._id);
+      assert.equal(item.brand, car.mainData.make);
+      assert.equal(item.condition, car.mainData.condition === 'selector_condition_new' ? 'Neu' : 'Gebraucht');
+      assert.equal(
+        item.availability,
+        car.offer.availabilityMode === 'selector_availabilityMode_always' ? 'Sofort' : 'Ab einem bestimmten Datum',
+      );
+    }
+  }],
+  ['20 real cars: brand aliases, apostrophe, unknown energy class and missing rates', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources());
+    const report = await run(world);
+    const items = await readItems(world.xml);
+    assert.equal(items.get(id(4)).title, 'Mercedes S 580');
+    assert.equal(items.get(id(6)).title, 'VW T-Roc');
+    assert.equal(items.get(id(12)).title, 'Kia cee&apos;d');
+    assert.equal(items.get(id(1)).energy_efficiency_class, 'D');
+    assert.equal(items.get(id(15)).energy_efficiency_class, undefined);
+    assert.equal(report.withoutEnergyClass, 1);
+    assert.equal(items.get(id(1)).custom_label_0, '309 EUR mtl.');
+    for (const n of [16, 17]) {
+      assert.equal(items.get(id(n)).installment, undefined);
+      assert.equal(items.get(id(n)).custom_label_0, undefined);
+    }
+    assert.equal(report.withRate, 18);
+  }],
+  ['sold car is left out and reported as removed by the next run', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources());
+    await run(world);
+    const cars = realSources();
+    cars[2].car.offer.offerAvailability = 'selector_offerAvailability_sold';
+    await writeSource(world, cars);
+    const report = await run(world, { at: new Date(NOW.getTime() + HOUR) });
+    assert.equal(report.excluded.reserved_or_sold, 1);
+    assert.equal((await readItems(world.xml)).has(id(3)), false);
+    assert.deepEqual(report.ids, { added: 0, removed: 1, kept: 19, removedSample: [id(3)] });
+  }],
+  ['reserved car is left out', async () => {
+    const world = await newWorld();
+    const cars = realSources();
+    cars[5].car.offer.offerAvailability = 'selector_offerAvailability_reserved';
+    await writeSource(world, cars);
+    const report = await run(world);
+    assert.equal(report.items, 19);
+    assert.equal(report.excluded.reserved_or_sold, 1);
+    assert.equal((await readItems(world.xml)).has(id(6)), false);
+  }],
+  ['car that went offline (not in the snapshot any more) drops out of the next full file', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources());
+    await run(world);
+    await writeSource(world, realSources().filter(source => source.car._id !== id(9)));
+    const report = await run(world, { at: new Date(NOW.getTime() + HOUR) });
+    assert.equal((await readItems(world.xml)).has(id(9)), false);
+    assert.equal(report.ids.removed, 1);
+  }],
+  ['car without a marketing image is left out, no placeholder', async () => {
+    const world = await newWorld();
+    world.noImage.add(id(7));
+    await writeSource(world, realSources());
+    const report = await run(world);
+    assert.equal(report.excluded.no_marketing_image, 1);
+    assert.equal((await readItems(world.xml)).has(id(7)), false);
+    assert.ok(!(await fs.readFile(world.xml, 'utf8')).includes('noimage'));
+  }],
+  ['price change shows up in the next run under the same id', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources());
+    await run(world);
+    const cars = realSources();
+    cars[0].car.price.currentSalesPrice = 25990;
+    await writeSource(world, cars);
+    const report = await run(world, { at: new Date(NOW.getTime() + HOUR) });
+    const item = (await readItems(world.xml)).get(id(1));
+    assert.equal(item.price, '25990 EUR');
+    assert.equal(item.sale_price, '25990 EUR');
+    assert.deepEqual(report.ids, { added: 0, removed: 0, kept: 20, removedSample: [] });
+  }],
+  ['car without a valid price is left out instead of "0 EUR"', async () => {
+    const world = await newWorld();
+    const cars = realSources();
+    cars[0].car.price.currentSalesPrice = 0;
+    delete cars[1].car.price.currentSalesPrice;
+    // garbage from upstream, not a valid schema value
+    (cars[2].car.price as any).currentSalesPrice = 'abc';
+    await writeSource(world, cars);
+    const report = await run(world);
+    assert.equal(report.excluded.no_valid_price, 3);
+    assert.equal(report.items, 17);
+    assert.ok(!(await fs.readFile(world.xml, 'utf8')).includes('>0 EUR<'));
+  }],
+  ['duplicate id is published once', async () => {
+    const world = await newWorld();
+    const cars = realSources();
+    cars.push({ car: clone(REAL_CARS[0]), images: [] });
+    await writeSource(world, cars);
+    const report = await run(world);
+    assert.equal(report.items, 20);
+    assert.equal(report.excluded.duplicate_id, 1);
+    const xml = await fs.readFile(world.xml, 'utf8');
+    assert.equal(xml.split(`<g:id>${id(1)}</g:id>`).length - 1, 1);
+  }],
+  ['car without an id is left out', async () => {
+    const world = await newWorld();
+    const cars = realSources();
+    cars[0].car._id = '';
+    await writeSource(world, cars);
+    const report = await run(world);
+    assert.equal(report.excluded.no_id, 1);
+    assert.equal(report.items, 19);
+  }],
+  ['source outage: empty snapshot is blocked, last good file and state untouched', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources());
+    await run(world);
+    const before = await fs.readFile(world.xml, 'utf8');
+    const lastGood = await fs.readFile(join(world.state, 'last-good.json'), 'utf8');
+    await writeSource(world, []);
+    await blocked(run(world, { at: new Date(NOW.getTime() + HOUR) }), 'source_empty');
+    assert.equal(await fs.readFile(world.xml, 'utf8'), before);
+    assert.equal(await fs.readFile(join(world.state, 'last-good.json'), 'utf8'), lastGood);
+    const report = await readReport(world);
+    assert.equal(report.status, 'blocked');
+    assert.equal(report.guard.code, 'source_empty');
+  }],
+  ['source outage: missing snapshot directory is blocked', async () => {
+    const world = await newWorld();
+    await blocked(run(world), 'source_empty');
+    assert.equal(await exists(world.xml), false);
+  }],
+  ['partial snapshot (missing chunk) is blocked', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources(), { skipChunk: 1 });
+    await blocked(run(world), 'source_partial');
+    assert.equal(await exists(world.xml), false);
+  }],
+  ['stale snapshot is blocked', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources(), { mtime: new Date(NOW.getTime() - 27 * HOUR) });
+    await blocked(run(world), 'source_stale');
+  }],
+  ['stock drop over 20% is blocked, published again with acceptDrop', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources());
+    await run(world);
+    await writeSource(world, realSources().slice(0, 10));
+    const later = new Date(NOW.getTime() + HOUR);
+    await blocked(run(world, { at: later }), 'count_drop');
+    assert.equal((await readItems(world.xml)).size, 20);
+    assert.ok(await exists(`${world.xml}.rejected`));
+    const report = await run(world, { at: later, guard: { acceptDrop: true } });
+    assert.equal(report.items, 10);
+    assert.equal(report.ids.removed, 10);
+  }],
+  ['legitimate empty stock (cars in the snapshot, none publishable) is blocked as published_too_small', async () => {
+    const world = await newWorld();
+    const cars = realSources().map(source => {
+      source.car.offer.offerAvailability = 'selector_offerAvailability_sold';
+      return source;
+    });
+    await writeSource(world, cars);
+    await blocked(run(world), 'published_too_small');
+  }],
+  ['a second run while one holds the lock is refused', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources());
+    await fs.mkdir(world.state, { recursive: true });
+    await fs.writeFile(join(world.state, 'run.lock'), '{}');
+    await blocked(run(world), 'locked');
+  }],
+  ['blocked run reports a stale last good file after maxStaleHours', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources());
+    await run(world);
+    await writeSource(world, []);
+    await blocked(run(world, { at: new Date(NOW.getTime() + 49 * HOUR) }), 'source_empty');
+    const report = await readReport(world);
+    assert.equal(report.stale, true);
+    assert.ok(report.lastGoodAgeHours > 48);
+  }],
+  ['publish is atomic: previous file kept as .prev, no temp file left, report has the metrics', async () => {
+    const world = await newWorld();
+    await writeSource(world, realSources());
+    await run(world);
+    await run(world, { at: new Date(NOW.getTime() + HOUR) });
+    assert.ok(await exists(`${world.xml}.prev`));
+    assert.equal(await exists(`${world.xml}.tmp`), false);
+    const report = await readReport(world);
+    assert.equal(report.status, 'published');
+    assert.equal(report.source.cars, 20);
+    assert.equal(report.source.files, 4);
+    assert.equal(report.source.ageHours, 1);
+    assert.equal(report.lastGood.publishedItems, 20);
+    assert.equal(typeof report.durationMs, 'number');
+  }],
+];
+
+(async () => {
+  let failed = 0;
+  for (const [name, fn] of tests) {
+    try {
+      await fn();
+      console.log(`ok   ${name}`);
+    } catch (e) {
+      failed += 1;
+      console.error(`FAIL ${name}\n     ${e.message}`);
+    }
+  }
+  if (failed) process.exit(1);
+})();