Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript
18.7 KB
Raw Blame
import { describe, expect, it } from 'vitest';
import {
  asOf, changedBy, changes, changesOn, foldRows, inForce, isTracked, lifeline, lifeRows, moment, momentLabel, momentNow, moments,
  previousState, seenAt, shortMoment, spanLabel, spanOf, stateAt, stepMoment,
} from './layerHistory.js';

const square = (x, size = 1) => ({ type: 'Polygon', coordinates: [[[x, 0], [x + size, 0], [x + size, size], [x, size], [x, 0]]] });
const line = (y) => ({ type: 'LineString', coordinates: [[0, y], [1, y]] });
const tracked = (states, extra = {}) => ({ type: 'Feature', geometry: states.findLast((s) => !s.gone)?.geometry,
  properties: { key: 'k', name: 'Front', states, ...extra } });

const front = tracked([
  { at: '2026-10-03', geometry: line(0) },
  { at: '2026-10-12', geometry: line(1), status: 'damaged' },
  { at: '2026-10-20', gone: true },
]);

describe('moments', () => {
  it('checks a day or a day and a time, and nothing else', () => {
    expect(moment('2026-10-12')).toBe('2026-10-12');
    expect(moment('2026-10-12T14:05')).toBe('2026-10-12T14:05');
    for (const bad of ['2026-02-30', '2026-10-12T24:00', '12/10/2026', '', null]) expect(moment(bad)).toBeNull();
  });

  it("says the moment it is on a layer's clock, to the day or to the minute", () => {
    const at = new Date('2026-10-16T22:30:00Z');
    expect(momentNow({ zone: 'UTC' }, at)).toBe('2026-10-16');
    // past midnight in Paris while UTC is still on the 16th
    expect(momentNow({ zone: 'Europe/Paris' }, at)).toBe('2026-10-17');
    expect(momentNow({ zone: 'Europe/Paris', precision: 'time' }, at)).toBe('2026-10-17T00:30');
    expect(momentNow({ zone: 'America/New_York', precision: 'time' }, at)).toBe('2026-10-16T18:30');
    // no clock, or one this browser does not know, reads on UTC
    expect(momentNow(null, at)).toBe('2026-10-16');
    expect(momentNow({ zone: 'Nowhere/Atlantis' }, at)).toBe('2026-10-16');
  });

  it('labels a day, a time, and always', () => {
    expect(momentLabel('2026-10-12')).toBe('12 Oct 2026');
    expect(momentLabel('2026-10-12T09:30')).toBe('12 Oct 2026 · 09:30');
    expect(momentLabel('')).toBe('Always');
  });

  it('lists every moment the layer changes at, plain days included, and steps through them', () => {
    const plain = { type: 'Feature', geometry: line(5), properties: { date: '2026-10-05', date_end: '2026-10-07' } };
    const list = moments({ features: [front, plain] });
    expect(list).toEqual(['2026-10-03', '2026-10-05', '2026-10-07', '2026-10-12', '2026-10-20']);
    expect(stepMoment(list, '2026-10-05', 1)).toBe('2026-10-07');
    expect(stepMoment(list, '2026-10-06', -1)).toBe('2026-10-05');
    expect(stepMoment(list, null, -1)).toBe('2026-10-20');
    expect(stepMoment(list, '2026-10-20', 1)).toBeNull();
  });

  it('is on only for a personal layer switched on', () => {
    expect(isTracked({ editable: true, track: { on: true } })).toBe(true);
    expect(isTracked({ editable: true, track: { on: false } })).toBe(false);
    expect(isTracked({ editable: false, track: { on: true } })).toBe(false);
  });
});

describe('a feature at a moment', () => {
  it('stands in the last state written at or before it, and nowhere before its first or after it went', () => {
    expect(stateAt(front, '2026-10-01')).toBeNull();
    expect(stateAt(front, '2026-10-03').geometry).toEqual(line(0));
    expect(stateAt(front, '2026-10-11T23:59').geometry).toEqual(line(0));
    const twelfth = stateAt(front, '2026-10-12');
    expect(twelfth.geometry).toEqual(line(1));
    expect(twelfth.properties.status).toBe('damaged');
    expect(twelfth.properties.states).toBeUndefined();
    expect(stateAt(front, '2026-10-20')).toBeNull();
  });

  it('reads a plain feature by its days, and an undated one as always there', () => {
    const plain = { geometry: line(0), properties: { date: '2026-10-05', date_end: '2026-10-07' } };
    expect(stateAt(plain, '2026-10-04')).toBeNull();
    expect(stateAt(plain, '2026-10-07T22:00')).toBe(plain);
    expect(stateAt(plain, '2026-10-08')).toBeNull();
    const always = { geometry: line(0), properties: {} };
    expect(stateAt(always, '1900-01-01')).toBe(always);
  });

  it('holds a day state from the start of its day, before every time of it', () => {
    const states = [{ at: '2026-10-12', geometry: line(0) }, { at: '2026-10-12T09:30', geometry: line(1) }];
    expect(inForce(states, '2026-10-12T09:00').geometry).toEqual(line(0));
    expect(inForce(states, '2026-10-12T09:30').geometry).toEqual(line(1));
  });

  it('knows the state before the one in force, which the trail draws', () => {
    expect(previousState(front, '2026-10-15').geometry).toEqual(line(0));
    expect(previousState(front, '2026-10-05')).toBeNull();
    expect(previousState(front, '2026-10-25')).toBeNull();
  });
});

describe('editing at the cursor', () => {
  it('lists the lifeline with the state at the cursor marked', () => {
    expect(lifeline(front, '2026-10-15').map((state) => [state.at, state.current, state.gone]))
      .toEqual([['2026-10-03', false, false], ['2026-10-12', true, false], ['2026-10-20', false, true]]);
    // with no cursor the latest drawn state is current
    expect(lifeline(front, null).find((state) => state.current).at).toBe('2026-10-12');
  });
});

describe('the layer as it stood', () => {
  const area = tracked([{ at: '2026-10-03', geometry: square(0) }, { at: '2026-10-12', geometry: square(0.5) }]);

  it('draws what stood then, and nothing more by default', () => {
    const drawn = asOf({ features: [front, area] }, '2026-10-05');
    expect(drawn.features.map((feature) => feature.geometry)).toEqual([line(0), square(0)]);
  });

  it('adds the previous state as a trail under the features', () => {
    const drawn = asOf({ features: [front] }, '2026-10-15', { trail: true });
    expect(drawn.features[0].properties.$trail).toBe(true);
    expect(drawn.features[0].geometry).toEqual(line(0));
    expect(drawn.features[1].geometry).toEqual(line(1));
  });

  it('reads the layer now when no moment is given', () => {
    const drawn = asOf({ features: [area] }, null, { trail: true });
    expect(drawn.features.at(-1).geometry).toEqual(square(0.5));
    expect(drawn.features[0].properties.$trail).toBe(true);
  });

  it('hatches what an area took and gave since its previous state', () => {
    const drawn = asOf({ features: [area] }, '2026-10-12', { since: 'previous' });
    const byChange = Object.fromEntries(drawn.features.filter((f) => f.properties.$change).map((f) => [f.properties.$change, f]));
    expect(Object.keys(byChange).sort()).toEqual(['gained', 'lost']);
    const ring = (feature) => feature.geometry.coordinates[0][0];
    expect(Math.min(...ring(byChange.gained).map(([x]) => x))).toBeCloseTo(1);
    expect(Math.max(...ring(byChange.lost).map(([x]) => x))).toBeCloseTo(0.5);
  });

  it('counts an area that was not there at the reference as all gained', () => {
    const drawn = asOf({ features: [area] }, '2026-10-12', { since: '2026-10-01' });
    const changed = drawn.features.filter((f) => f.properties.$change);
    expect(changed.map((f) => f.properties.$change)).toEqual(['gained']);
  });

  it('leaves lines out of the gains and losses', () => {
    expect(changes(front, line(0), line(1))).toEqual([]);
  });
});

describe('what an editor works on at a moment', () => {
  it('reshapes each tracked feature as it stood, keeps its history, and marks what was not there', () => {
    const plain = { type: 'Feature', geometry: line(5), properties: { key: 'p', date: '2026-10-15' } };
    const [front, later] = seenAt([tracked([
      { at: '2026-10-03', geometry: line(0) }, { at: '2026-10-12', geometry: line(1), status: 'damaged' }]), plain], '2026-10-05');
    expect(front.geometry).toEqual(line(0));
    expect(front.properties.status).toBeUndefined();
    expect(front.properties.states).toHaveLength(2);
    expect(later.properties.$absent).toBe(true);
    const list = [plain];
    expect(seenAt(list, null)).toBe(list);
  });
});

describe('the day the layer is read on', () => {
  const point = (properties) => ({ type: 'Feature', geometry: { type: 'Point', coordinates: [0, 0] }, properties: { key: Math.random(), ...properties } });
  const read = (features, at, options) => asOf({ features }, at, options).features;

  it('rings what appeared or changed that very day, and nothing with no moment', () => {
    const [moved, born, old] = read([front, point({ date: '2026-10-12' }), point({ date: '2026-10-01' })], '2026-10-12');
    expect(moved.properties.$new).toBe(true);
    expect(born.properties.$new).toBe(true);
    expect(old.properties.$new).toBeUndefined();
    expect(read([point({ date: '2026-10-12' })], null)[0].properties.$new).toBeUndefined();
  });

  it('keeps a lasting thing as it is, and an event faded after its day for good unless given a window', () => {
    const strike = point({ date: '2026-10-05', event: true });
    const post = point({ date: '2026-10-05' });
    expect(read([strike], '2026-10-05')[0].properties.$fade).toBeUndefined();
    expect(read([strike], '2026-10-08')[0].properties.$fade).toBe(true);
    // no window: a year on, the strike is still there, faded
    expect(read([strike], '2027-10-05')[0].properties.$fade).toBe(true);
    expect(read([strike, post], '2026-10-20', { window: 7 })).toHaveLength(1);
    expect(read([strike], '2026-10-20', { window: 30 })).toHaveLength(1);
    expect(read([post], '2026-10-20')[0].properties.$fade).toBeUndefined();
  });

  it("reads events with no moment against the layer's last change, not the calendar", () => {
    const strike = point({ date: '2025-01-10', event: true });
    const last = point({ date: '2025-01-12' });
    const [kept] = read([strike, last], null);
    expect(kept.properties.$fade).toBe(true);
  });
});

describe('a reading kept', () => {
  const point = (properties) => ({ type: 'Feature', geometry: { type: 'Point', coordinates: [0, 0] }, properties: { key: Math.random(), ...properties } });

  it('hands back the same reading for a day where nothing moved, and a new one when something did', () => {
    const layer = { features: [front, point({ date: '2026-10-01' })] };
    const fifth = asOf(layer, '2026-10-05');
    expect(asOf(layer, '2026-10-08')).toBe(fifth);
    // the 12th moves the front and rings it, the 13th only takes the ring off
    const twelfth = asOf(layer, '2026-10-12');
    expect(twelfth).not.toBe(fifth);
    expect(asOf(layer, '2026-10-13')).not.toBe(twelfth);
    expect(asOf(layer, '2026-10-14')).toBe(asOf(layer, '2026-10-13'));
    // what the map draws of the past is part of the reading
    expect(asOf(layer, '2026-10-05', { trail: true })).not.toBe(fifth);
  });

  it('takes an event fading or going as a change', () => {
    const layer = { features: [point({ date: '2026-10-05', event: true })] };
    const day = asOf(layer, '2026-10-05');
    const faded = asOf(layer, '2026-10-06');
    expect(faded).not.toBe(day);
    expect(asOf(layer, '2026-10-09')).toBe(faded);
    expect(asOf(layer, '2026-10-20').features).toHaveLength(1);
    expect(asOf(layer, '2026-10-20', { window: 7 }).features).toHaveLength(0);
  });

  it('reads every day of a busy layer as a fresh reading would', () => {
    let seed = 3;
    const random = () => ((seed = (seed * 16807) % 2147483647) / 2147483647);
    const features = Array.from({ length: 40 }, (_, index) => {
      if (index % 4 === 3) return point({ date: `2026-10-${String(1 + Math.floor(random() * 20)).padStart(2, '0')}`, event: index % 8 === 3 });
      const states = [];
      for (let day = 1 + Math.floor(random() * 6); day <= 28; day += 3 + Math.floor(random() * 9)) {
        states.push(random() < 0.15 ? { at: `2026-10-${String(day).padStart(2, '0')}`, gone: true }
          : { at: `2026-10-${String(day).padStart(2, '0')}${random() < 0.3 ? 'T14:00' : ''}`, geometry: square(random()) });
      }
      return tracked(states);
    });
    const layer = { features };
    for (const options of [{}, { trail: true }, { trail: true, since: 'previous' }, { since: '2026-10-10', window: 3 }]) {
      for (let day = 1; day <= 30; day += 1) {
        for (const at of [`2026-10-${String(day).padStart(2, '0')}`, `2026-10-${String(day).padStart(2, '0')}T18:00`]) {
          expect(asOf(layer, at, options)).toEqual(asOf(structuredClone(layer), at, options));
        }
      }
      expect(asOf(layer, null, options)).toEqual(asOf(structuredClone(layer), null, options));
    }
  });
});

describe('when a feature shows, as the editor says it', () => {
  const plain = (properties = {}) => ({ type: 'Feature', geometry: line(0), properties: { key: 'p', ...properties } });

  it('reads a plain feature from its days and a history from its states', () => {
    expect(spanOf(plain())).toEqual({ start: '', end: '', ends: 'last', changes: 0, unknown: false });
    expect(spanOf(plain({ date: '2026-10-03', date_end: '2026-10-09' }))).toEqual({ start: '2026-10-03', end: '2026-10-09', ends: 'last', changes: 0, unknown: false });
    expect(spanOf(front)).toEqual({ start: '2026-10-03', end: '2026-10-20', ends: 'gone', changes: 1, unknown: false });
    const always = tracked([{ at: '', geometry: line(0) }, { at: '2026-10-12', geometry: line(1) }]);
    expect(spanOf(always)).toEqual({ start: '', end: '', ends: 'gone', changes: 1, unknown: false });
  });

  it('says an end nobody knows only of a feature with no end', () => {
    expect(spanOf(plain({ date: '2026-10-03', end_unknown: true })).unknown).toBe(true);
    expect(spanOf(plain({ date: '2026-10-03', date_end: '2026-10-09', end_unknown: true })).unknown).toBe(false);
    expect(spanOf({ ...front, properties: { ...front.properties, end_unknown: true } }).unknown).toBe(false);
    expect(spanLabel(spanOf(plain({ date: '2026-10-13', end_unknown: true })), { year: 2026 })).toBe('13 Oct → ?');
    expect(spanLabel(spanOf(plain({ end_unknown: true })), { year: 2026 })).toBe('Always → ?');
  });

  it('says it in a few words, the year only when it is not this one', () => {
    const year = 2026;
    expect(spanLabel(spanOf(plain()), { year })).toBe('Always');
    expect(spanLabel({ start: '2026-10-12', end: '' }, { year })).toBe('From 12 Oct');
    expect(spanLabel({ start: '', end: '2026-10-20' }, { year })).toBe('Until 20 Oct');
    expect(spanLabel({ start: '2025-12-30', end: '2026-01-02' }, { year })).toBe('30 Dec 2025 → 2 Jan');
    expect(spanLabel({ start: '2026-10-12', end: '' }, { year, event: true })).toBe('12 Oct');
    expect(spanLabel({ start: '', end: '' }, { year, event: true })).toBe('No day');
    expect(shortMoment('2026-10-12T14:00', year)).toBe('12 Oct 14:00');
  });

  it('says what each state brought', () => {
    expect(lifeline(front, null).map((row) => row.what)).toEqual(['Appears', 'Reshaped · Damaged', 'Gone']);
    const marker = { type: 'Feature', geometry: { type: 'Point', coordinates: [1, 1] }, properties: { key: 'm', states: [
      { at: '', geometry: { type: 'Point', coordinates: [0, 0] } },
      { at: '2026-10-05', gone: true },
      { at: '2026-10-08', geometry: { type: 'Point', coordinates: [0, 0] } },
      { at: '2026-10-09', geometry: { type: 'Point', coordinates: [1, 1] } },
      { at: '2026-10-10', geometry: { type: 'Point', coordinates: [1, 1] }, status: 'destroyed' },
    ] } };
    expect(lifeline(marker, null).map((row) => row.what)).toEqual(['Shown', 'Gone', 'Back', 'Moved', 'Destroyed']);
  });

  it('marks the state a dated edit rewrites, or where a new one goes', () => {
    const shown = (rows) => rows.map((row) => [row.at, row.editing, row.ghost]);
    // with no moment, or with no date, an edit counts on every day alike: no row is its own
    expect(shown(lifeRows(front, null))).toEqual([['2026-10-03', false, false], ['2026-10-12', false, false], ['2026-10-20', false, false]]);
    expect(shown(lifeRows(front, '2026-10-15', 'fix'))).toEqual(shown(lifeRows(front, null)));
    // a day between two states: a new one there
    expect(shown(lifeRows(front, '2026-10-15', 'new'))).toEqual([
      ['2026-10-03', false, false], ['2026-10-12', false, false], ['2026-10-15', false, true], ['2026-10-20', false, false]]);
    // on a state's own day the edit rewrites it
    expect(lifeRows(front, '2026-10-12', 'new').filter((row) => row.editing).map((row) => row.at)).toEqual(['2026-10-12']);
    // where it is not shown, nothing is edited
    expect(lifeRows(front, '2026-10-25', 'new').some((row) => row.editing || row.ghost)).toBe(false);
  });

  it('knows what a feature changed by date, which an edit with no date leaves alone', () => {
    expect(changedBy(front)).toEqual({ shape: '2026-10-12', status: '2026-10-12' });
    const struck = tracked([{ at: '', geometry: line(0) }, { at: '2026-10-08', geometry: line(0), status: 'destroyed' }, { at: '2026-10-09', gone: true }]);
    expect(changedBy(struck)).toEqual({ shape: '', status: '2026-10-08' });
    expect(changedBy(plain({ date: '2026-10-03' }))).toEqual({ shape: '', status: '' });
  });

  it('shows a plain feature the history a dated edit would give it', () => {
    expect(lifeRows(plain(), null)).toHaveLength(1);
    expect(lifeRows(plain(), '2026-10-15', 'fix')).toHaveLength(1);
    expect(lifeRows(plain(), '2026-10-15', 'new').map((row) => [row.at, row.what, row.ghost])).toEqual([['', 'Shown', false], ['2026-10-15', 'Next edit', true]]);
    expect(lifeRows(plain({ date: '2026-10-20' }), '2026-10-15', 'new')).toHaveLength(1);
  });

  it('knows what happens on the day the layer is shown at', () => {
    expect(changesOn(front, '2026-10-12T09:00')).toBe(true);
    expect(changesOn(front, '2026-10-20')).toBe(true);
    expect(changesOn(front, '2026-10-15')).toBe(false);
    expect(changesOn(plain({ date: '2026-10-15' }), '2026-10-15')).toBe(true);
    expect(changesOn(plain(), '2026-10-15')).toBe(false);
    expect(changesOn(front, null)).toBe(false);
  });
});

describe('a long history', () => {
  const day = (index) => `2026-${String(1 + Math.floor(index / 28)).padStart(2, '0')}-${String(1 + (index % 28)).padStart(2, '0')}`;
  const many = (count, extra = {}) => Array.from({ length: count }, (_, index) => ({ at: day(index), what: 'Moved', current: false, ...(extra[index] ?? {}) }));

  it('keeps a short one whole', () => {
    const rows = many(7, { 6: { current: true } });
    expect(foldRows(rows)).toBe(rows);
  });

  it('keeps the first, the last and the dates round the edit, counting the rest', () => {
    const rows = many(100, { 50: { editing: true }, 99: { current: true } });
    const shown = foldRows(rows);
    expect(shown.map((row) => (row.fold ? `+${row.fold}` : row.at))).toEqual([day(0), '+48', day(49), day(50), day(51), '+47', day(99)]);
    expect(shown[1].at).toBe(day(1));
  });

  it('falls back to the date shown, then to the last, and never folds a lone date', () => {
    expect(foldRows(many(9, { 2: { current: true } })).map((row) => (row.fold ? `+${row.fold}` : row.at)))
      .toEqual([day(0), day(1), day(2), day(3), '+4', day(8)]);
    expect(foldRows(many(9)).map((row) => (row.fold ? `+${row.fold}` : row.at)))
      .toEqual([day(0), '+6', day(7), day(8)]);
  });
});