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
16.1 KB
Raw Blame
import { emptyFilter, normalizeFilter } from './entityFilter.js';

const CATEGORIES = new Set(['statement', 'media', 'case_activity']);
/**
 * The colours a track may be given, by name.
 *
 * A track is a question the analyst wrote, and on a busy axis its colour is how the
 * answer is read at a glance. Left unset the lane keeps the **category** colours —
 * statement, media, activity — which is what the legend explains; a chosen colour
 * says the analyst wants this reading told apart from the others instead, and it wins
 * for that track only. Names rather than hex so the palette stays the app's own
 * (`--anno-*`) and a saved view cannot carry an unreadable colour.
 */
export const TRACK_COLORS = ['red', 'blue', 'amber', 'green', 'magenta', 'orange'];

/** The colour as CSS, or nothing at all — an unset track must inherit the category
 *  colours rather than a grey stand-in. Ordered with the palette above. */
export function trackTint(color) {
  const index = TRACK_COLORS.indexOf(color);
  return index < 0 ? undefined : `var(--anno-${index + 1})`;
}
const RELATIONS = new Set(['any', 'owner', 'about', 'place', 'source']);
/** The files a file lane draws: the sources' pictures and videos, or the imagery the
 *  app pictured from above (satellite, map screenshots, Compare, Detect). */
const FILE_LANES = new Set(['sources', 'imagery']);
const ROLES = new Set(['occurred', 'observed', 'valid', 'unset']);

const unique = (values, allowed = null, limit = 500) => [
  ...new Set(
    (Array.isArray(values) ? values : [])
      .filter((value) => typeof value === 'string' && value && (!allowed || allowed.has(value)))
      .slice(0, limit)
  ),
];

export function timelineTrack(value, index = 0) {
  const raw = value && typeof value === 'object' ? value : {};
  const query = raw.query && typeof raw.query === 'object' ? raw.query : {};
  const categories = unique(raw.categories, CATEGORIES, 3);
  return {
    id: typeof raw.id === 'string' && raw.id ? raw.id.slice(0, 64) : `track-${index + 1}`,
    label: typeof raw.label === 'string' && raw.label.trim()
      ? raw.label.trim().slice(0, 80)
      : `Track ${index + 1}`,
    categories: categories.length ? categories : ['statement'],
    query: {
      filter: normalizeFilter(query.filter ?? emptyFilter()),
      terms: query.terms && typeof query.terms === 'object' ? query.terms : {},
      label: typeof query.label === 'string' ? query.label.slice(0, 300) : '',
      relation: RELATIONS.has(query.relation) ? query.relation : 'any',
      roles: unique(query.roles, ROLES, 4),
      // The Media Library's working-files switch: frames, captures, collages and
      // renders the case made itself stay off the track. Absent reads as off, which
      // is what every track saved before it meant.
      ...(query.collected_only === true ? { collected_only: true } : {}),
      // A lane that draws each of its events as the file it dates (`fileLane`).
      ...(FILE_LANES.has(query.as_files) ? { as_files: query.as_files } : {}),
      // The dated markers of the analyst's own map layers (`layersLane`).
      ...(query.as_layers === true ? { as_layers: true } : {}),
    },
    color: TRACK_COLORS.includes(raw.color) ? raw.color : '',
    collapsed: raw.collapsed === true,
    hidden: unique(raw.hidden),
    pinned: unique(raw.pinned),
  };
}

/** The kinds of file an event can put at its date. */
const SITUATED = ['media', 'capture'];

/**
 * The Media lane: the sources' pictures and videos where the analyst dated them, and
 * nowhere else.
 *
 * A file's date is the one an analyst gives it: the date typed on a proof (stated for
 * the footage it rests on), a correction, an event about the file or citing it ("seen
 * in" a video). Each of those is a Claim, so the lane holds the Claims tied to a file
 * and draws each one as that file, with its name and its picture. What a file says
 * about itself (the post's date, the camera's clock) is a clue and not a finding: it
 * stays on the File dates track, added on purpose, and one press away when an event is
 * added from the file. What the app pictured from above is not a source's footage, so
 * it has a lane of its own (`imageryLane`).
 */
export function mediaLane() {
  return timelineTrack({
    id: 'files', label: 'Media', categories: ['statement'], query: { as_files: 'sources' },
  });
}

/** The Imagery lane: satellite captures, map screenshots, Compare renders and the
 *  pictures Detect keeps, where an event dates them. Added from the track list. */
export function imageryLane() {
  return timelineTrack({
    id: 'imagery', label: 'Imagery', categories: ['statement'], query: { as_files: 'imagery' },
  });
}

/**
 * The My layers lane: the markers the analyst dated in their own map layers. Read
 * from the layers on disk rather than the case's events, since a marker is not one;
 * added from the track list.
 */
export function layersLane() {
  return timelineTrack({
    id: 'layers', label: 'My layers', categories: ['statement'], query: { as_layers: true },
  });
}

export function drawsLayers(track) {
  return track?.query?.as_layers === true;
}

/**
 * Timeline entries for the dated features of personal layers, one per feature.
 *
 * `drawings` pairs each layer row with the collection it draws. A day is a whole
 * day: it opens at midnight and closes at the last second, on UTC, which is how
 * the time strip on the map reads it too.
 */
export function layerItems(drawings) {
  const items = [];
  for (const { row, collection } of drawings) {
    for (const feature of collection?.features ?? []) {
      const properties = feature.properties ?? {};
      // a history switched off is hidden, here as on the map: the feature reads by its days
      if (row.track?.on && Array.isArray(properties.states) && properties.states.length && properties.key) {
        items.push(...stateItems(row, feature));
        continue;
      }
      if (!/^\d{4}-\d{2}-\d{2}$/.test(properties.date ?? '') || !properties.key) continue;
      const last = properties.date_end > properties.date ? properties.date_end : properties.date;
      const point = feature.geometry?.type === 'Point' ? feature.geometry.coordinates : null;
      items.push({
        id: `layer:${row.name}:${properties.key}`,
        kind: 'layer',
        category: 'statement',
        label: properties.name || 'Unnamed marker',
        raw: properties.date,
        precision: 'day',
        earliest: `${properties.date}T00:00:00Z`,
        latest: `${last}T23:59:59Z`,
        layer: {
          name: row.name, title: row.title, key: properties.key, group: properties.category ?? '',
          status: properties.status ?? '', links: properties.links ?? [],
          external: properties.provenance === 'external',
          at: point ? { lon: point[0], lat: point[1] } : null,
        },
      });
    }
  }
  return items.sort((a, b) => a.earliest.localeCompare(b.earliest));
}

/**
 * A tracked feature on the Timeline: one bar per state, from its day to the day
 * before the next one, and a mark on the day it went. What it was then is what
 * the card says, so a front line reads as the spans it held.
 */
function stateItems(row, feature) {
  const properties = feature.properties;
  const states = properties.states;
  const name = properties.name || 'Unnamed feature';
  const items = [];
  states.forEach((state, index) => {
    const day = String(state.at ?? '').slice(0, 10);
    if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) return;
    const next = String(states[index + 1]?.at ?? '').slice(0, 10);
    const last = !state.gone && next > day ? isoDayBefore(next) : day;
    // where the map is sent: the point, or where a line or an area starts
    const point = state.gone ? null : firstPosition(state.geometry?.coordinates);
    items.push({
      id: `layer:${row.name}:${properties.key}:${state.at}`,
      kind: 'layer',
      category: 'statement',
      label: state.gone ? `${name} · gone` : index && states[index - 1]?.at ? `${name} · changed` : name,
      raw: state.at,
      precision: 'day',
      earliest: `${day}T00:00:00Z`,
      latest: `${last < day ? day : last}T23:59:59Z`,
      layer: {
        name: row.name, title: row.title, key: properties.key, group: properties.category ?? '',
        status: state.status ?? '', links: properties.links ?? [],
        external: properties.provenance === 'external',
        at: point ? { lon: point[0], lat: point[1] } : null,
        moment: state.at,
      },
    });
  });
  return items;
}

function firstPosition(node) {
  if (!Array.isArray(node)) return null;
  return typeof node[0] === 'number' ? node : firstPosition(node[0]);
}

function isoDayBefore(day) {
  const date = new Date(`${day}T00:00:00Z`);
  date.setUTCDate(date.getUTCDate() - 1);
  return date.toISOString().slice(0, 10);
}

/** Whether a track draws its events as the files they date. */
export function drawsFiles(track) {
  return FILE_LANES.has(track?.query?.as_files);
}

/**
 * The file an event puts at its date: the one the server named (`file`, with its
 * preview), or else the first file it is about, then the first it cites.
 */
export function situatedFile(item) {
  if (item?.file?.id) return item.file;
  for (const key of ['subject_entities', 'source_entities']) {
    const entry = (item?.[key] ?? []).find((entity) => SITUATED.includes(entity?.type));
    if (entry) return { id: entry.id, label: entry.label, type: entry.type };
  }
  return null;
}

/**
 * What a fresh reading opens on: the files where the analyst dated them, over the
 * events. A saved view keeps the tracks it was saved with.
 */
export function defaultTimelineTracks() {
  return [
    mediaLane(),
    timelineTrack({ id: 'events', label: 'Events', categories: ['statement'] }),
  ];
}

/** The File dates preset. `collectedOnly` holds back the working files. */
export function mediaTrack(tracks = [], { collectedOnly = true } = {}) {
  const used = new Set(tracks.map((track) => track.id));
  let id = 'media';
  for (let n = 2; used.has(id); n += 1) id = `media-${n}`;
  return timelineTrack({
    id, label: 'File dates', categories: ['media'],
    query: collectedOnly ? { collected_only: true } : {},
  });
}

/** Whether a track leaves the case's working files out. */
export function holdsBackWorkingFiles(track) {
  return track?.categories?.includes('media') && track.query?.collected_only === true;
}

/** The same track with its working files let in. */
export function withWorkingFiles(track) {
  const { collected_only: _held, ...query } = track.query ?? {};
  return { ...track, query };
}

export function normalizeTimelineTracks(value) {
  const raw = Array.isArray(value) ? value.slice(0, 20) : [];
  const tracks = raw.length ? raw.map(timelineTrack) : defaultTimelineTracks();
  const seen = new Set();
  return tracks.map((track, index) => {
    // The suffix counts up. A fixed one is loop-invariant, so a saved view whose
    // ids already hold the deduped spelling (['t-3', 't', 't']) spun here
    // forever and froze the tab.
    let id = track.id;
    for (let n = index + 1; seen.has(id); n += 1) id = `${track.id}-${n}`;
    seen.add(id);
    return { ...track, id };
  });
}

export function trackPresets(types = []) {
  const ofType = (type, relation = 'about') => timelineTrack({
    id: `preset-${type}`,
    label: types.find((entry) => entry.type === type)?.label ?? type,
    categories: ['statement'],
    query: { relation, terms: { type }, filter: { ...emptyFilter(), types: [type] } },
  });
  return [
    timelineTrack({ id: 'preset-events', label: 'Events', categories: ['statement'] }),
    { ...mediaLane(), id: 'preset-files' },
    { ...imageryLane(), id: 'preset-imagery' },
    { ...layersLane(), id: 'preset-layers' },
    ofType('person'),
    ofType('place', 'place'),
    timelineTrack({
      id: 'preset-media', label: 'File dates', categories: ['media'], query: { collected_only: true },
    }),
    timelineTrack({
      id: 'preset-sources', label: 'Sources', categories: ['statement'],
      query: { relation: 'source' },
    }),
    timelineTrack({ id: 'preset-activity', label: 'Case activity', categories: ['case_activity'] }),
  ];
}

export function copyTimelineTrack(track, tracks) {
  const used = new Set(tracks.map((entry) => entry.label.toLocaleLowerCase()));
  const stem = `${track.label} copy`;
  let label = stem;
  let index = 2;
  while (used.has(label.toLocaleLowerCase())) label = `${stem} ${index++}`;
  return {
    ...timelineTrack(track),
    id: `track-${globalThis.crypto?.randomUUID?.() ?? Date.now()}-${Math.random().toString(16).slice(2)}`,
    label,
    collapsed: false,
  };
}

export function moveTimelineTrack(tracks, from, to) {
  if (from === to || from < 0 || to < 0 || from >= tracks.length || to >= tracks.length) return tracks;
  const next = [...tracks];
  const [moved] = next.splice(from, 1);
  next.splice(to, 0, moved);
  return next;
}

export function timelineTrackQuery(track) {
  return JSON.stringify({
    ...track.query,
    hidden: track.hidden,
  });
}

function groupKeys(item, groupBy, typeName) {
  if (groupBy === 'subject') {
    return item.subject_entities?.length
      ? item.subject_entities : [{ id: 'none', label: 'No subject' }];
  }
  if (groupBy === 'place') {
    return item.place_entities?.length
      ? item.place_entities : [{ id: 'none', label: 'No place' }];
  }
  if (groupBy === 'source') {
    return item.source_entities?.length
      ? item.source_entities : [{ id: 'none', label: 'No evidence' }];
  }
  if (groupBy === 'type') {
    const types = [...new Set((item.subject_entities ?? []).map((entry) => entry.type).filter(Boolean))];
    if (!types.length && item.owner_type) types.push(item.owner_type);
    if (!types.length) return [{ id: 'none', label: 'Unknown type' }];
    return types.map((type) => ({ id: type, label: typeName(type), type }));
  }
  if (groupBy === 'role') {
    const role = item.time_role || 'Not set';
    return [{ id: role, label: role }];
  }
  return [];
}

export function groupedTimelineTracks(tracks, itemSets, groupBy = 'none', typeName = (type) => type) {
  if (groupBy === 'none') return tracks.map((track) => ({ ...track, items: itemSets[track.id] ?? [] }));
  const result = [];
  for (const track of tracks) {
    const groups = new Map();
    for (const item of itemSets[track.id] ?? []) {
      for (const key of groupKeys(item, groupBy, typeName)) {
        const id = String(key.id || key.label || 'other');
        const group = groups.get(id) ?? { id, label: key.label || id, items: [] };
        group.items.push(item);
        groups.set(id, group);
      }
    }
    if (!groups.size) result.push({ ...track, items: [], groupLabel: 'No matches' });
    else for (const group of groups.values()) {
      result.push({
        ...track,
        id: `${track.id}:group:${group.id}`,
        parentId: track.id,
        label: group.label,
        groupLabel: track.label,
        items: group.items,
      });
    }
  }
  return result;
}

export function timelineViewState(value) {
  const raw = value && typeof value === 'object' ? value : {};
  const tracks = normalizeTimelineTracks(raw.tracks);
  return {
    from: typeof raw.from === 'string' ? raw.from : '',
    to: typeof raw.to === 'string' ? raw.to : '',
    timezone: typeof raw.timezone === 'string' && raw.timezone
      ? raw.timezone.slice(0, 80) : 'UTC',
    // `zone:<IANA name>` is the fourth reading, for an investigation at the other end
    // of the world that the case has no saved point in yet. Validated by shape only:
    // whether this machine can load the name is asked when the axis is drawn, so a
    // view made where the zone exists does not lose it on a stricter box. `case` is
    // the zone the case's places stand in, found again wherever the view is opened.
    // A view saved before there was a choice read UTC, and still does.
    zoneChoice: typeof raw.zone_choice === 'string'
      && /^(utc|case|machine|place:[^\s]{1,64}|zone:[A-Za-z0-9+\-_/]{1,64})$/.test(raw.zone_choice)
      ? raw.zone_choice : 'utc',
    viewMode: raw.view_mode === 'list' ? 'list' : 'plot',
    groupBy: ['subject', 'type', 'place', 'source', 'role'].includes(raw.group_by)
      ? raw.group_by : 'none',
    tracks,
    categories: unique(tracks.flatMap((track) => track.categories), CATEGORIES, 3),
    entity: raw.entity?.id ? { id: raw.entity.id, label: raw.entity.label || raw.entity.id } : null,
  };
}