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.4 KB
Raw Blame
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { relationTypes as ontologyVocabulary } from '../../e2e/app.fixture.js';
// This instance is never given a registry, so it is also the "before the fetch
// lands" case: every surface renders against an empty vocabulary at first paint.
import {
  confidenceLevels as coldLevels,
  isRatable as coldRatable,
  relationOptions as coldOptions,
  relationVerb as coldVerb,
} from './relations.svelte.js';

const get = vi.fn();
const post = vi.fn();
vi.mock('./api.js', () => ({ api: { get: (...a) => get(...a), post: (...a) => post(...a) } }));

const LEVELS = [
  { value: 3, label: 'Certain', hint: 'established and corroborated' },
  { value: 2, label: 'Probable', hint: 'more likely than not' },
  { value: 1, label: 'Possible' },
  { value: -1, label: 'Ruled out' },
];

const VOCABULARY = [
  {
    type: 'located-at',
    label: 'was recorded at',
    from_types: ['capture', 'media'],
    to_types: ['place'],
    hint: 'the camera stood at this point',
    manual: true,
    ratable: true,
  },
  {
    type: 'depicts',
    label: 'shows',
    from_types: ['capture', 'media'],
    to_types: ['place'],
    manual: true,
    ratable: true,
  },
  {
    type: 'same-image-as',
    label: 'is the same picture as',
    from_types: ['media'],
    to_types: ['media'],
    manual: false,
    ratable: true,
  },
  {
    type: 'in-network',
    label: 'is in network',
    inverse_label: 'contains',
    from_types: ['ip', 'network'],
    to_types: ['network'],
    manual: true,
    ratable: true,
  },
  // Symmetric, and the one verb carrying a free note: the tie is real, what kind of
  // tie it is is a word only the analyst has.
  {
    type: 'associated-with',
    label: 'is associated with',
    inverse_label: 'is associated with',
    from_types: ['organization', 'person'],
    to_types: ['organization', 'person'],
    manual: true,
    ratable: true,
    qualifier: 'How they are tied',
  },
  // The one verb the registry heads apart: a document naming something is a pointer,
  // not a finding about where it is.
  {
    type: 'mentions',
    label: 'mentions',
    from_types: ['note', 'post'],
    to_types: ['media', 'place'],
    hint: 'refers to it, without having been made from it',
    group: 'Mentions',
    action: 'mention',
    manual: true,
    ratable: true,
  },
];

/** Answers each registry route, so a test can drop one without dropping both. */
const serve = (routes = {}) => (url) => {
  const table = {
    '/api/cases/relation-types': VOCABULARY,
    '/api/cases/confidence-levels': LEVELS,
    ...routes,
  };
  const answer = table[url];
  return answer instanceof Error ? Promise.reject(answer) : Promise.resolve(answer);
};

let relations;

beforeEach(async () => {
  vi.resetModules();
  get.mockReset();
  post.mockReset();
  get.mockImplementation(serve());
  relations = await import('./relations.svelte.js');
});

describe('the relation vocabulary', () => {
  it('is fetched once however many surfaces ask for it', async () => {
    await Promise.all([
      relations.loadRelationTypes(),
      relations.loadRelationTypes(),
      relations.loadRelationTypes(),
    ]);
    // two routes, read together once: the vocabulary and the levels an edge may hold
    expect(get).toHaveBeenCalledTimes(2);
    expect(get).toHaveBeenCalledWith('/api/cases/relation-types');
    expect(get).toHaveBeenCalledWith('/api/cases/confidence-levels');
  });

  it('leaves a surface usable before the fetch lands', () => {
    expect(coldVerb('located-at')).toBe('located-at');
    expect(coldOptions('place', 'media')).toEqual([]);
  });

  it('names an edge in words once the registry is in', async () => {
    await relations.loadRelationTypes();
    expect(relations.relationVerb('located-at')).toBe('was recorded at');
    expect(relations.relationVerb('same-image-as')).toBe('is the same picture as');
    expect(relations.relationVerb('invented-by-hand')).toBe('invented-by-hand');
  });

  it('leaves the panel usable when the registry cannot be read', async () => {
    vi.resetModules();
    get.mockRejectedValue(new Error('offline'));
    const degraded = await import('./relations.svelte.js');
    await degraded.loadRelationTypes();
    expect(degraded.relationVerb('located-at')).toBe('located-at');
    expect(degraded.relationOptions('place', 'media')).toEqual([]);
  });
});

describe('relationOptions', () => {
  beforeEach(() => relations.loadRelationTypes());

  it('records which end the subject sits on, because the vocabulary is directed', () => {
    // from a place: the photo is the subject of the edge, the place its object
    expect(relations.relationOptions('place', 'media')).toEqual([
      { type: 'located-at', label: 'was recorded at', group: '', direction: 'in' },
      { type: 'depicts', label: 'shows', group: '', direction: 'in' },
    ]);
    // from the photo, the same two edges run outward
    expect(relations.relationOptions('media', 'place').map((o) => o.direction)).toEqual([
      'out',
      'out',
    ]);
  });

  it('never offers a machine-only relation', () => {
    expect(relations.relationOptions('media', 'media')).toEqual([]);
  });

  it('offers nothing for a pair the ontology has no reading for', () => {
    expect(relations.relationOptions('place', 'place')).toEqual([]);
    expect(relations.relationOptions('post', 'post')).toEqual([]);
  });

  it('carries the heading its verb declares, so a surface never sorts by type name', () => {
    const [pointer] = relations.relationOptions('note', 'place');
    expect(pointer).toEqual({
      type: 'mentions',
      label: 'mentions',
      group: 'Mentions',
      direction: 'out',
    });
    expect(relations.relationOptions('media', 'place').every((o) => o.group === '')).toBe(true);
  });

  it('keeps mentions out of the relation gesture', () => {
    expect(relations.relationOptions('note', 'place', 'relation')).toEqual([]);
    expect(relations.relationOptions('note', 'place', 'mention')).toEqual([
      { type: 'mentions', label: 'mentions', group: 'Mentions', direction: 'out' },
    ]);
    expect(relations.relationAction('mentions')).toBe('mention');
    expect(relations.relationAction('located-at')).toBe('relation');
  });

  it('puts a headed verb last however the registry declares it', async () => {
    // the first option is the default reading a picker files, and a pointer is never
    // the strongest thing a pair can say — declaration order must not decide that
    vi.resetModules();
    get.mockImplementation(
      serve({
        '/api/cases/relation-types': [
          {
            ...VOCABULARY.find((entry) => entry.type === 'mentions'),
            from_types: ['note'],
            to_types: ['place'],
          },
          {
            ...VOCABULARY.find((entry) => entry.type === 'located-at'),
            from_types: ['note'],
          },
        ],
      })
    );
    const hostile = await import('./relations.svelte.js');
    await hostile.loadRelationTypes();

    expect(hostile.relationOptions('note', 'place').map((o) => o.type)).toEqual([
      'located-at',
      'mentions',
    ]);
  });
});

describe('relatableTypes', () => {
  beforeEach(() => relations.loadRelationTypes());

  it('lists what can sit at the other end, so a picker searches only those', () => {
    expect(relations.relatableTypes('place').sort()).toEqual(['capture', 'media', 'note', 'post']);
    expect(relations.relatableTypes('media').sort()).toEqual(['note', 'place', 'post']);
    // a headed verb widens the picker like any other: a pointer still needs a target
    expect(relations.relatableTypes('post').sort()).toEqual(['media', 'place']);
  });

  it('gives relations and mentions separate target sets', () => {
    expect(relations.relatableTypes('note', 'relation')).toEqual([]);
    expect(relations.relatableTypes('note', 'mention').sort()).toEqual(['media', 'place']);
  });

  it('offers IP and nested-network links in both readable directions', () => {
    expect(relations.relatableTypes('ip', 'relation')).toEqual(['network']);
    expect(relations.relatableTypes('network', 'relation').sort()).toEqual(['ip', 'network']);
    expect(relations.relationOptions('ip', 'network', 'relation')).toContainEqual({
      type: 'in-network', label: 'is in network', group: '', direction: 'out',
    });
    expect(relations.relationOptions('network', 'ip', 'relation')).toContainEqual({
      type: 'in-network', label: 'contains', group: '', direction: 'in',
    });
    expect(relations.relationOptions('network', 'network', 'relation')).toEqual([
      { type: 'in-network', label: 'is in network', group: '', direction: 'out' },
      { type: 'in-network', label: 'contains', group: '', direction: 'in' },
    ]);
  });

  it('offers a symmetric verb once, not the same sentence twice', () => {
    // A parent network *contains* a child while the child *is in* the parent: two
    // readings, two lines. Two people are associated with each other in one word, so
    // the second line would ask the analyst to choose between two identical options.
    expect(relations.relationOptions('person', 'person', 'relation')).toEqual([
      { type: 'associated-with', label: 'is associated with', group: '', direction: 'out' },
    ]);
  });

  it('reads a symmetric row as current from the far end too', () => {
    // The regression the dedup above caused: offered once, the entity on the far end
    // found no inward reading to match, so every association read as an older
    // connection — badged out-of-matrix and stripped of its controls on exactly one
    // of the two panels showing it.
    const tie = {
      link: { id: 'l1', type: 'associated-with', provenance: { status: 'confirmed' } },
      entity: { type: 'person' },
      direction: 'in',
    };
    expect(relations.isCurrentConnection('person', tie)).toBe(true);
    expect(relations.isCurrentConnection('person', { ...tie, direction: 'out' })).toBe(true);
    // An asymmetric verb still has to match: its two readings are two findings, and
    // only one of them may be legal for a given pair.
    expect(relations.isSymmetric('in-network')).toBe(false);
    expect(relations.isSymmetric('associated-with')).toBe(true);
    expect(
      relations.isCurrentConnection('ip', {
        link: { id: 'l2', type: 'in-network', provenance: { status: 'confirmed' } },
        entity: { type: 'network' },
        direction: 'in',
      })
    ).toBe(false);
  });

  it('says which verb carries a free note, and which do not', () => {
    // It belongs to the verb, never to the edge: a note every edge could hold would
    // leave nothing saying what an edge *is*.
    expect(relations.relationQualifier('associated-with')).toBe('How they are tied');
    expect(relations.relationQualifier('in-network')).toBe('');
    expect(relations.relationQualifier('mentions')).toBe('');
    // an older registry with no such key answers the same as a verb declining one
    expect(relations.relationQualifier('nothing-like-it')).toBe('');
  });
});

describe('the complete browser ontology', () => {
  let complete;

  beforeEach(async () => {
    vi.resetModules();
    get.mockImplementation(
      serve({ '/api/cases/relation-types': ontologyVocabulary })
    );
    complete = await import('./relations.svelte.js');
    await complete.loadRelationTypes();
  });

  it('makes every manual endpoint reachable through its own frontend gesture', () => {
    for (const entry of ontologyVocabulary.filter((row) => row.manual)) {
      for (const fromType of entry.from_types) {
        for (const toType of entry.to_types) {
          expect(
            complete.relatableTypes(fromType, entry.action),
            `${entry.type}: ${fromType} must reach ${toType}`
          ).toContain(toType);
          expect(
            complete.relationOptions(fromType, toType, entry.action),
            `${entry.type}: ${fromType} must offer its outward reading for ${toType}`
          ).toContainEqual({
            type: entry.type,
            label: entry.label,
            group: entry.group,
            direction: 'out',
          });
        }
      }
    }
  });

  it('keeps relation, mention and Claim connectors out of each other’s buttons', () => {
    for (const entry of ontologyVocabulary.filter((row) => row.manual)) {
      const otherActions = ['relation', 'mention', 'claim'].filter(
        (action) => action !== entry.action
      );
      for (const action of otherActions) {
        expect(
          complete.relationOptions(entry.from_types[0], entry.to_types[0], action)
            .some((option) => option.type === entry.type),
          `${entry.type} leaked into ${action}`
        ).toBe(false);
      }
    }
  });
});

describe('saveRelation', () => {
  it('files the endpoints in the order the link type requires', async () => {
    await relations.saveRelation('case-1', 'e_place', {
      entityId: 'e_photo',
      type: 'located-at',
      direction: 'in',
    });
    expect(post).toHaveBeenCalledWith('/api/cases/case-1/links', {
      from_id: 'e_photo',
      to_id: 'e_place',
      type: 'located-at',
    });

    await relations.saveRelation('case-1', 'e_photo', {
      entityId: 'e_place',
      type: 'located-at',
      direction: 'out',
    });
    expect(post).toHaveBeenLastCalledWith('/api/cases/case-1/links', {
      from_id: 'e_photo',
      to_id: 'e_place',
      type: 'located-at',
    });
  });
});

describe('how sure an edge says the analyst is', () => {
  it('serves the levels the API declares, coarsest word last', async () => {
    await relations.loadRelationTypes();

    expect(relations.confidenceLevels().map((l) => l.value)).toEqual([3, 2, 1, -1]);
    expect(relations.confidenceLabel(-1)).toBe('Ruled out');
    expect(relations.confidenceLabel(2)).toBe('Probable');
  });

  it('reads an unrated edge as nothing at all, never as a level', async () => {
    await relations.loadRelationTypes();

    // absent is the lack of a rating, so it has no word and is not in the list
    expect(relations.confidenceLabel(null)).toBe('');
    expect(relations.confidenceLabel(undefined)).toBe('');
    expect(relations.confidenceLevels().some((l) => l.value == null)).toBe(false);
  });

  it('says which link types may carry a rating at all', async () => {
    await relations.loadRelationTypes();

    expect(relations.isRatable('located-at')).toBe(true);
    // a derivation is not in this registry, so it can never be offered one
    expect(relations.isRatable('derived-from')).toBe(false);
  });

  it('offers no level before the registry lands, so no surface guesses one', () => {
    expect(coldLevels()).toEqual([]);
    expect(coldRatable('located-at')).toBe(false);
  });

  it('drops a failed read so the next surface retries both routes', async () => {
    vi.resetModules();
    get.mockImplementation(serve({ '/api/cases/confidence-levels': new Error('offline') }));
    const cold = await import('./relations.svelte.js');

    await cold.loadRelationTypes();
    // one route failing leaves the whole registry empty rather than half-loaded
    expect(cold.confidenceLevels()).toEqual([]);
    expect(cold.relationVerb('located-at')).toBe('located-at');

    get.mockImplementation(serve());
    await cold.loadRelationTypes();
    expect(cold.confidenceLevels()).toHaveLength(4);
    expect(cold.relationVerb('located-at')).toBe('was recorded at');
  });
});

describe('the vocabulary explains itself', () => {
  it('says what a verb means, where the words alone are ambiguous', async () => {
    await relations.loadRelationTypes();

    expect(relations.relationHint('located-at')).toBe('the camera stood at this point');
    // nothing invented locally for a verb the registry has never heard of
    expect(relations.relationHint('bewitches')).toBe('');
  });

  it('says which verbs head their own section, and does not decide it here', async () => {
    await relations.loadRelationTypes();

    expect(relations.relationGroup('mentions')).toBe('Mentions');
    expect(relations.relationGroup('located-at')).toBe('');
    expect(relations.relationGroup('bewitches')).toBe('');
  });

  it('places a rating on the scale for the control that offers it', async () => {
    await relations.loadRelationTypes();

    expect(relations.confidenceHint(3)).toBe('established and corroborated');
    expect(relations.confidenceHint(null)).toBe('');
  });
});

describe('directed and media-aware endpoints', () => {
  it('uses the inverse reading and refuses a non-media file kind', async () => {
    vi.resetModules();
    get.mockImplementation(
      serve({
        '/api/cases/relation-types': [
          {
            ...VOCABULARY[0],
            label: 'was recorded at',
            inverse_label: 'was recorded here',
            from_media_kinds: ['image', 'video', 'audio'],
          },
        ],
      })
    );
    const directed = await import('./relations.svelte.js');
    await directed.loadRelationTypes();

    const place = { type: 'place', attrs: {} };
    const audio = { type: 'media', attrs: { kind: 'audio' } };
    const file = { type: 'media', attrs: { kind: 'file' } };
    expect(directed.relationOptions(place, audio)[0].label).toBe('was recorded here');
    expect(directed.relationOptions(place, file)).toEqual([]);
    expect(directed.relatableTypes(audio)).toEqual(['place']);
    expect(directed.relatableTypes(file)).toEqual([]);
    expect(directed.relationReading('located-at', 'in')).toBe('was recorded here');
  });

  it('recognizes whether a stored row still fits the current matrix', async () => {
    await relations.loadRelationTypes();
    const subject = { type: 'media', attrs: { kind: 'image' } };
    const current = {
      link: { type: 'located-at' },
      entity: { type: 'place', attrs: {} },
      direction: 'out',
    };
    const older = { ...current, direction: 'in' };

    expect(relations.isCurrentConnection(subject, current)).toBe(true);
    expect(relations.isCurrentConnection(subject, older)).toBe(false);
  });

  it('asks before a stated edge is taken back, and never before a proposal', () => {
    // The words live here so the three surfaces that offer the act cannot word it three
    // ways, and the split is what keeps the review gesture one click: a tool's proposal
    // costs the analyst nothing to refuse, their own statement is held nowhere afterwards.
    expect(relations.retractionWarning({ provenance: { status: 'suggested' } })).toBe(null);

    const stated = relations.retractionWarning({ provenance: { status: 'confirmed' } });
    expect(stated.title).toBe('Remove this relation?');
    expect(stated.detail).toContain('Nothing holds a removed edge');

    expect(relations.retractionWarning({}, 'mention').title).toBe('Remove this mention?');
  });
});