@crvouga/atlas 0.2.0 → 0.3.0

package/packages/visualizer/src/find/corpus.ts

@@ -0,0 +1,368 @@
+import type { CheckSlot, EvidenceView } from '@crvouga/atlas/reports/evidence-view';
+import type { RunStatus } from '@crvouga/atlas/schema';
+
+import type { AtlasView, ItemStatus } from '../data/model';
+import { worstOf } from '../data/model/status';
+import { featureModel, scenarioLabel, slotsByScenario } from '../evidence/gherkin';
+import { kindOfFile, outlinePath, specFile } from '../spec-kind';
+import type { FindDoc, FindField, FindStatus, FindTarget } from './rank';
+
+export type CorpusChart = { readonly id: string; readonly name: string };
+
+export type CorpusState = {
+  readonly name: string;
+  readonly chartId: string;
+  readonly kind: string;
+  readonly description: string;
+  readonly status: ItemStatus;
+};
+
+export type CorpusTransition = {
+  readonly id: string;
+  readonly chartId: string;
+  readonly event: string;
+  readonly source: string;
+  readonly target: string | null;
+  readonly status: ItemStatus;
+  readonly carriedBy?: string | null;
+};
+
+export type CorpusPath = {
+  readonly id: string;
+  readonly name: string;
+  readonly status: RunStatus;
+  readonly events: readonly string[];
+};
+
+export type CorpusJourney = {
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly chartId: string;
+  readonly events: readonly string[];
+  readonly endsIn: readonly string[];
+  readonly status: ItemStatus;
+  readonly paths: readonly CorpusPath[];
+};
+
+export type CorpusFile = { readonly path: string; readonly title: string };
+
+export type CorpusSlot = {
+  readonly key: string;
+  readonly id: string;
+  readonly title: string;
+  readonly specPath: string | null;
+  readonly status: FindStatus;
+  readonly detail: string;
+  readonly recording: boolean;
+};
+
+export type CorpusSource = {
+  readonly charts: readonly CorpusChart[];
+  readonly states: readonly CorpusState[];
+  readonly transitions: readonly CorpusTransition[];
+  readonly journeys: readonly CorpusJourney[];
+  readonly files: readonly CorpusFile[];
+  readonly slots: readonly CorpusSlot[];
+  readonly texts: ReadonlyMap<string, string>;
+};
+
+function itemStatus(status: ItemStatus): FindStatus {
+  if (status === 'passed') return 'passed';
+  if (status === 'failed' || status === 'flaky') return 'failed';
+  if (status === 'not-yet-run') return 'running';
+  return 'none';
+}
+
+function runStatus(status: RunStatus): FindStatus {
+  if (status === 'passed') return 'passed';
+  if (status === 'failed' || status === 'flaky') return 'failed';
+  return 'not-run';
+}
+
+function chartTarget(chartId: string, search: FindTarget['search']): FindTarget {
+  return { to: '/chart/$chartId', chartId, search };
+}
+
+function specTarget(kind: string, spec: string, check?: string, recording = false): FindTarget {
+  return {
+    to: '/specs/$kind',
+    kind,
+    search: { spec, ...(check ? { check } : {}), ...(recording ? { view: 'recording' as const } : {}) }
+  };
+}
+
+/** The first slot that has a timeline, opened as a recording. */
+function timelineTarget(kind: string | null, file: string, slots: readonly CorpusSlot[]): FindTarget | null {
+  if (!kind) return null;
+  const slot = slots.find((item) => item.recording);
+  return slot ? specTarget(kind, file, slot.id, true) : null;
+}
+
+function fieldsOf(title: string, steps: string, description: string, path: string): FindField[] {
+  const fields: FindField[] = [{ name: 'title', text: title }];
+  if (steps) fields.push({ name: 'steps', text: steps });
+  if (description) fields.push({ name: 'description', text: description });
+  if (path) fields.push({ name: 'path', text: path });
+  return fields;
+}
+
+function places(names: readonly string[]): string {
+  const unique = [...new Set(names.filter(Boolean))];
+  if (unique.length <= 3) return unique.join(', ');
+  return `${unique.slice(0, 3).join(', ')}, and ${unique.length - 3} more`;
+}
+
+function slotsFor(file: string, slots: readonly CorpusSlot[]): CorpusSlot[] {
+  return slots.filter((slot) => slot.specPath === outlinePath(file) || (slot.specPath !== null && specFile(slot.specPath) === file));
+}
+
+function worstStatus(statuses: readonly FindStatus[]): FindStatus {
+  const rank: Record<FindStatus, number> = { failed: 3, running: 2, 'not-run': 1, passed: 0, none: 0 };
+  return statuses.reduce((worst, status) => (rank[status] > rank[worst] ? status : worst), 'passed');
+}
+
+const ACTION = /^\s*action\s+([A-Za-z_][A-Za-z0-9_]*)/gm;
+
+function actionsIn(text: string): string[] {
+  return [...new Set([...text.matchAll(ACTION)].map((match) => match[1]!))];
+}
+
+function runDoc(slot: CorpusSlot, title: string, kind: string | null, file: string): FindDoc {
+  const recording = timelineTarget(kind, file, [slot]);
+  return {
+    id: `run:${slot.key}`,
+    group: 'Runs',
+    kind: 'run',
+    title,
+    subtitle: file,
+    fields: fieldsOf(title, '', slot.detail, file),
+    status: slot.status,
+    related: [],
+    // Enter opens the recording when this check has a timeline.
+    target: recording ?? (kind ? specTarget(kind, file, slot.id) : { to: '/' as const, search: {} }),
+    recording
+  };
+}
+
+/** Every flow, spec and recorded run the finder can open. */
+export function buildCorpus(source: CorpusSource): FindDoc[] {
+  const chartName = new Map(source.charts.map((chart) => [chart.id, chart.name]));
+  const docs: FindDoc[] = [];
+  const seenRuns = new Set<string>();
+
+  for (const state of source.states) {
+    if (state.kind !== 'screen' && state.kind !== 'final') continue;
+    docs.push({
+      id: `screen:${state.chartId}:${state.name}`,
+      group: 'Flows',
+      kind: 'screen',
+      title: state.name,
+      subtitle: chartName.get(state.chartId) ?? '',
+      fields: fieldsOf(state.name, '', state.description, ''),
+      status: itemStatus(state.status),
+      related: [],
+      target: chartTarget(state.chartId, { screen: state.name }),
+      recording: null
+    });
+  }
+
+  const events = new Map<string, CorpusTransition[]>();
+  for (const transition of source.transitions) {
+    if (!transition.event) continue;
+    const key = `${transition.chartId}\0${transition.event}`;
+    const group = events.get(key);
+    if (group) group.push(transition);
+    else events.set(key, [transition]);
+  }
+  for (const group of events.values()) {
+    const first = group.find((transition) => !transition.carriedBy) ?? group[0]!;
+    const where = places(group.flatMap((transition) => [transition.source, transition.target ?? '']));
+    docs.push({
+      id: `event:${first.chartId}:${first.event}`,
+      group: 'Flows',
+      kind: 'event',
+      title: first.event,
+      subtitle: where,
+      fields: fieldsOf(first.event, '', where, ''),
+      status: itemStatus(worstOf(group.map((transition) => transition.status), 'spec-only')),
+      related: [],
+      target: chartTarget(first.chartId, { event: first.id }),
+      recording: null
+    });
+  }
+
+  for (const journey of source.journeys) {
+    const pathIds = journey.paths.map((path) => `path:${journey.id}:${path.id}`);
+    docs.push({
+      id: `journey:${journey.id}`,
+      group: 'Flows',
+      kind: 'journey',
+      title: journey.name,
+      subtitle: chartName.get(journey.chartId) ?? '',
+      fields: fieldsOf(journey.name, journey.events.join('\n'), [journey.description, ...journey.endsIn].filter(Boolean).join('\n'), ''),
+      status: itemStatus(journey.status),
+      related: pathIds,
+      target: chartTarget(journey.chartId, { journey: journey.id }),
+      recording: null
+    });
+    for (const path of journey.paths) {
+      docs.push({
+        id: `path:${journey.id}:${path.id}`,
+        group: 'Runs',
+        kind: 'run',
+        title: path.name || journey.name,
+        subtitle: journey.name,
+        fields: fieldsOf(path.name || journey.name, path.events.join('\n'), '', ''),
+        status: runStatus(path.status),
+        related: [],
+        target: chartTarget(journey.chartId, { journey: journey.id }),
+        recording: null
+      });
+    }
+  }
+
+  const pushRun = (slot: CorpusSlot, title: string, kind: string | null, file: string) => {
+    const id = `run:${slot.key}`;
+    if (seenRuns.has(id)) return;
+    seenRuns.add(id);
+    docs.push(runDoc(slot, title, kind, file));
+  };
+
+  for (const file of source.files) {
+    const kind = kindOfFile(file.path);
+    if (!kind) continue;
+    const text = source.texts.get(file.path);
+    const mine = slotsFor(file.path, source.slots);
+    if (kind.id === 'gherkin' && text) {
+      let feature: ReturnType<typeof featureModel> = null;
+      try {
+        feature = featureModel(text);
+      } catch {
+        feature = null;
+      }
+      if (feature) {
+        const filed = slotsByScenario(feature, mine as unknown as CheckSlot[]);
+        docs.push({
+          id: `spec:${file.path}`,
+          group: 'Specs',
+          kind: 'spec',
+          title: feature.name || file.title,
+          subtitle: file.path,
+          fields: fieldsOf(feature.name || file.title, '', feature.description, file.path),
+          status: null,
+          related: [],
+          target: specTarget(kind.id, file.path),
+          recording: null
+        });
+        for (const rule of feature.rules) {
+          for (const scenario of rule.scenarios) {
+            if (scenario.background) continue;
+            const recorded = (filed.byScenario.get(scenario.name) ?? []) as unknown as CorpusSlot[];
+            const steps = [
+              ...scenario.steps.map((step) => `${step.keyword} ${step.text}`.trim()),
+              ...scenario.examples.flatMap((example) => example.rows.flat())
+            ].join('\n');
+            docs.push({
+              id: `scenario:${file.path}:${scenario.name}`,
+              group: 'Specs',
+              kind: 'scenario',
+              title: scenario.name,
+              subtitle: feature.name || file.title,
+              fields: fieldsOf(scenario.name, steps, [rule.name ?? '', rule.description, scenario.description].filter(Boolean).join('\n'), file.path),
+              status: recorded.length ? worstStatus(recorded.map((slot) => slot.status)) : null,
+              related: recorded.map((slot) => `run:${slot.key}`),
+              target: specTarget(kind.id, file.path, recorded[0]?.id ?? `scenario:${scenario.name}`),
+              recording: timelineTarget(kind.id, file.path, recorded)
+            });
+          }
+        }
+        for (const slot of mine) pushRun(slot, scenarioLabel(feature.name, slot.title), kind.id, file.path);
+        continue;
+      }
+    }
+    if (kind.id === 'quint' && text) {
+      for (const name of actionsIn(text)) {
+        docs.push({
+          id: `action:${file.path}:${name}`,
+          group: 'Specs',
+          kind: 'action',
+          title: name,
+          subtitle: file.title,
+          fields: fieldsOf(name, '', '', file.path),
+          status: null,
+          related: mine.map((slot) => `run:${slot.key}`),
+          target: specTarget(kind.id, file.path, mine[0]?.id),
+          recording: timelineTarget(kind.id, file.path, mine)
+        });
+      }
+    }
+    docs.push({
+      id: `spec:${file.path}`,
+      group: 'Specs',
+      kind: 'spec',
+      title: file.title,
+      subtitle: file.path,
+      fields: fieldsOf(file.title, '', text ?? '', file.path),
+      status: null,
+      related: mine.map((slot) => `run:${slot.key}`),
+      target: specTarget(kind.id, file.path, mine[0]?.id),
+      recording: timelineTarget(kind.id, file.path, mine)
+    });
+    for (const slot of mine) pushRun(slot, slot.title, kind.id, file.path);
+  }
+
+  for (const slot of source.slots) {
+    const file = slot.specPath ? specFile(slot.specPath) : '';
+    pushRun(slot, slot.title, file ? kindOfFile(file)?.id ?? null : null, file);
+  }
+  return docs;
+}
+
+/** The view and the evidence the page already holds, in the shape `buildCorpus` reads. */
+export function corpusFrom(view: AtlasView | null, files: readonly string[], titleOf: (file: string) => string, evidence: EvidenceView, texts: ReadonlyMap<string, string>): FindDoc[] {
+  const slots: CorpusSlot[] = [];
+  const take = (slot: CheckSlot) => {
+    slots.push({
+      key: slot.key,
+      id: slot.id,
+      title: slot.title,
+      specPath: slot.specPath,
+      status: slot.status,
+      detail: slot.outcomes.map((outcome) => outcome.row.detail).filter(Boolean).join('\n'),
+      recording: slot.outcomes.some((outcome) => outcome.row.testId !== null)
+    });
+  };
+  for (const entry of evidence.specs.values()) for (const slot of entry.slots) take(slot);
+  for (const slot of evidence.unassigned) take(slot);
+  return buildCorpus({
+    charts: view ? [...view.charts.values()].map((chart) => ({ id: chart.id, name: chart.name })) : [],
+    states: view ? [...view.states.values()].map((state) => ({ name: state.name, chartId: state.chartId, kind: state.kind, description: state.description, status: state.status })) : [],
+    transitions: view
+      ? [...view.transitions.values()].map((transition) => ({
+          id: transition.id,
+          chartId: transition.chartId,
+          event: transition.event,
+          source: transition.source,
+          target: transition.target,
+          status: transition.status,
+          carriedBy: transition.carriedBy
+        }))
+      : [],
+    journeys: view
+      ? view.journeys.map((journey) => ({
+          id: journey.id,
+          name: journey.name,
+          description: journey.description,
+          chartId: journey.chartIds[0] ?? '',
+          events: journey.events,
+          endsIn: journey.endsIn,
+          status: journey.status,
+          paths: journey.runPaths.map((path) => ({ id: path.id, name: path.name, status: path.status, events: path.steps.map((step) => step.event) }))
+        }))
+      : [],
+    files: files.map((path) => ({ path, title: titleOf(path) })),
+    slots,
+    texts
+  });
+}

package/packages/visualizer/src/find/open.ts

@@ -0,0 +1,51 @@
+import { useSyncExternalStore } from 'react';
+
+let open = false;
+let help = false;
+const listeners = new Set<() => void>();
+
+function emit() {
+  for (const listener of listeners) listener();
+}
+
+export function subscribeFinder(listener: () => void) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function isFinderOpen() {
+  return open;
+}
+
+export function isHelpOpen() {
+  return help;
+}
+
+/** Recording keys stay put while either layer is up. */
+export function finderBlocksKeys() {
+  return open || help;
+}
+
+export function setFinderOpen(value: boolean) {
+  open = value;
+  if (value) help = false;
+  emit();
+}
+
+export function toggleFinder() {
+  setFinderOpen(!open);
+}
+
+export function setHelpOpen(value: boolean) {
+  help = value;
+  if (value) open = false;
+  emit();
+}
+
+export function useFinderOpen() {
+  return useSyncExternalStore(subscribeFinder, isFinderOpen, () => false);
+}
+
+export function useHelpOpen() {
+  return useSyncExternalStore(subscribeFinder, isHelpOpen, () => false);
+}

package/packages/visualizer/src/find/rank.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, test } from 'bun:test';
+
+import { buildCorpus, type CorpusSource } from './corpus';
+import { canonical, notationOf, rank, stem, type FindDoc } from './rank';
+
+const FEATURE = `Feature: Working the list
+  A person keeps a list of todos.
+
+  Scenario: Finish every todo and clear them
+    When they tap "Mark all done"
+    And they clear completed
+
+  Scenario: Add a todo
+    When they add a todo
+
+  Scenario: Evening routine
+    When they tap "Mark all done"
+`;
+
+const QUINT = `module todo {
+  action add = true
+  action mark_all_done = true
+  action clear_completed = true
+}
+`;
+
+function todoSource(): CorpusSource {
+  const screens = Array.from({ length: 12 }, (_, index) => ({
+    name: `Open todo list ${index + 1}`,
+    chartId: 'app',
+    kind: 'screen',
+    description: '',
+    status: 'passed' as const
+  }));
+  return {
+    charts: [{ id: 'app', name: 'Todo' }],
+    states: [...screens, { name: 'No todos', chartId: 'app', kind: 'screen', description: '', status: 'passed' }],
+    transitions: [
+      { id: 'mark', chartId: 'app', event: 'Marks all done', source: 'Has items', target: 'Done', status: 'passed' },
+      { id: 'add-carried', chartId: 'app', event: 'Adds a todo', source: 'Desktop', target: 'Has items', status: 'passed', carriedBy: 'phone' },
+      { id: 'add', chartId: 'app', event: 'Adds a todo', source: 'No todos', target: 'Has items', status: 'passed' },
+      { id: 'add-again', chartId: 'app', event: 'Adds a todo', source: 'Has items', target: 'Has items', status: 'passed' },
+      { id: 'clear', chartId: 'app', event: 'Clears completed todos', source: 'Has items', target: 'No todos', status: 'passed' },
+      { id: 'throw', chartId: 'app', event: 'Throw the list away', source: 'Has items', target: 'No todos', status: 'passed' }
+    ],
+    journeys: [
+      {
+        id: 'weekend',
+        name: 'Plans a weekend',
+        description: 'A person finishes it before Monday.',
+        chartId: 'app',
+        events: ['Adds a todo', 'Marks all done'],
+        endsIn: ['Done'],
+        status: 'failed',
+        paths: [
+          { id: 'slipped', name: 'Saturday slipped', status: 'failed', events: ['Adds a todo', 'Marks all done'] },
+          { id: 'held', name: 'Saturday held', status: 'passed', events: ['Adds a todo', 'Marks all done'] }
+        ]
+      }
+    ],
+    files: [
+      { path: 'working-the-list.feature', title: 'Working the list' },
+      { path: 'todo.qnt', title: 'todo.qnt' },
+      { path: 'todo-app.scxml', title: 'Todo app' }
+    ],
+    slots: [
+      {
+        key: 'lists/evening',
+        id: 'lists/evening',
+        title: 'Evening routine',
+        specPath: 'specs/working-the-list.feature',
+        status: 'passed',
+        detail: 'Recorded on Saturday.',
+        recording: true
+      }
+    ],
+    texts: new Map([
+      ['working-the-list.feature', FEATURE],
+      ['todo.qnt', QUINT]
+    ])
+  };
+}
+
+const docs = buildCorpus(todoSource());
+
+function titles(query: string) {
+  return rank(docs, query).map((hit) => hit.doc.title);
+}
+
+function above(query: string, earlier: string, later: string) {
+  const list = titles(query);
+  const from = list.indexOf(earlier);
+  const to = list.indexOf(later);
+  expect(from, list.join(' | ')).toBeGreaterThanOrEqual(0);
+  expect(to, list.join(' | ')).toBeGreaterThan(from);
+}
+
+describe('everyday words', () => {
+  test('stems and classes meet', () => {
+    expect(stem('marking')).toBe('mark');
+    expect(stem('marked')).toBe('mark');
+    expect(stem('marks')).toBe('mark');
+    expect(stem('todos')).toBe('todo');
+    expect(canonical('marking')).toBe('complete');
+    expect(canonical('completed')).toBe('complete');
+    expect(canonical('finished')).toBe('complete');
+    expect(canonical('adds')).toBe('add');
+    expect(canonical('clears')).toBe('remove');
+  });
+
+  test('marking a todo complete finds the flows that finish the list', () => {
+    const list = titles('Marking todo as complete');
+    for (const title of ['Marks all done', 'Finish every todo and clear them', 'mark_all_done', 'Plans a weekend']) {
+      above('Marking todo as complete', title, 'No todos');
+    }
+    expect(list.indexOf('Marks all done'), list.join(' | ')).toBeGreaterThanOrEqual(0);
+    const finish = rank(docs, 'Marking todo as complete').find((hit) => hit.doc.title === 'Finish every todo and clear them');
+    expect(finish?.snippet).toContain('Mark all done');
+  });
+
+  test('a matched scenario lists its recorded check', () => {
+    const hits = rank(docs, 'Marking todo as complete');
+    const scenario = hits.findIndex((hit) => hit.doc.kind === 'scenario' && hit.doc.title === 'Evening routine');
+    const run = hits.findIndex((hit) => hit.doc.id === 'run:lists/evening');
+    expect(scenario, hits.map((hit) => hit.doc.title).join(' | ')).toBeGreaterThanOrEqual(0);
+    expect(run).toBe(scenario + 1);
+    expect(hits[run]?.doc.title).toBe('Evening routine');
+    expect(hits[run]?.snippet).toContain('Mark all done');
+  });
+
+  test('adding a todo finds the add flows', () => {
+    above('Add new todo', 'Adds a todo', 'No todos');
+    above('Add new todo', 'Add a todo', 'No todos');
+  });
+
+  test('removing a todo finds clearing', () => {
+    above('remove todo', 'Clears completed todos', 'No todos');
+    above('remove todo', 'clear_completed', 'No todos');
+    above('remove todo', 'Clears completed todos', 'Throw the list away');
+  });
+
+  test('a mistyped phrase still finds the flow', () => {
+    above('makring todo complte', 'Marks all done', 'No todos');
+  });
+
+  test('an empty box lists journeys and then failing checks', () => {
+    const list = titles('');
+    expect(list[0]).toBe('Plans a weekend');
+    expect(list).toContain('Saturday slipped');
+    expect(list).not.toContain('Saturday held');
+    expect(list).not.toContain('Open todo list 1');
+    expect(titles('the')).toEqual(list);
+  });
+});
+
+function quiet(title: string): FindDoc {
+  return {
+    id: title,
+    group: 'Specs',
+    kind: 'spec',
+    title,
+    subtitle: '',
+    fields: [{ name: 'title', text: title }],
+    status: null,
+    related: [],
+    target: { to: '/', search: {} },
+    recording: null
+  };
+}
+
+test('a kind word keeps only that kind of spec', () => {
+  const marking = titles('Marking todo as complete');
+  for (const query of ['gherkin', 'features', 'scenarios', 'cucumber']) {
+    const list = titles(query);
+    expect(list, query).toContain('Add a todo');
+    expect(list, query).toContain('Finish every todo and clear them');
+    expect(list, query).not.toContain('Adds a todo');
+    expect(list, query).not.toContain('mark_all_done');
+    expect(rank(docs, query).every((hit) => notationOf(hit.doc) === 'gherkin')).toBe(true);
+  }
+  for (const query of ['quint', 'models', 'qnt']) {
+    const list = titles(query);
+    expect(list, query).toContain('add');
+    expect(list, query).toContain('mark_all_done');
+    expect(list, query).not.toContain('Add a todo');
+    expect(list, query).not.toContain('Adds a todo');
+  }
+  for (const query of ['statecharts', 'statechart', 'scxml', 'state machine']) {
+    const list = titles(query);
+    expect(list, query).toContain('Adds a todo');
+    expect(list, query).toContain('Plans a weekend');
+    expect(list, query).not.toContain('Add a todo');
+    expect(list, query).not.toContain('mark_all_done');
+    expect(rank(docs, query).every((hit) => notationOf(hit.doc) === 'statechart')).toBe(true);
+  }
+  const gherkinAdd = titles('add a feature');
+  expect(gherkinAdd).toContain('Add a todo');
+  expect(gherkinAdd).not.toContain('Adds a todo');
+  expect(gherkinAdd).not.toContain('add');
+  const quintAdd = titles('quint add');
+  expect(quintAdd).toContain('add');
+  expect(quintAdd).not.toContain('Add a todo');
+  expect(titles('gherkn add todo')).toContain('Add a todo');
+  expect(titles('gherkn add todo')).not.toContain('Adds a todo');
+  expect(marking).toContain('Marks all done');
+  expect(marking).toContain('Finish every todo and clear them');
+});
+
+test('decision tables, alloy, and openslo filter the same way', () => {
+  const typed = (title: string, notation: string): FindDoc => ({
+    id: title,
+    group: 'Specs',
+    kind: 'spec',
+    title,
+    subtitle: '',
+    fields: [{ name: 'title', text: title }],
+    status: null,
+    related: [],
+    target: { to: '/specs/$kind', kind: notation, search: { spec: title } },
+    recording: null
+  });
+  const kinds = [typed('Ship the decision', 'dmn'), typed('Keep the alloy', 'alloy'), typed('Hold the slo', 'openslo'), typed('Add a todo', 'gherkin')];
+  expect(rank(kinds, 'dmn').map((hit) => hit.doc.title)).toEqual(['Ship the decision']);
+  expect(rank(kinds, 'decision table').map((hit) => hit.doc.title)).toEqual(['Ship the decision']);
+  expect(rank(kinds, 'alloy').map((hit) => hit.doc.title)).toEqual(['Keep the alloy']);
+  expect(rank(kinds, 'openslo').map((hit) => hit.doc.title)).toEqual(['Hold the slo']);
+  const both = rank(kinds, 'gherkin alloy').map((hit) => hit.doc.title);
+  expect(both).toContain('Add a todo');
+  expect(both).toContain('Keep the alloy');
+  expect(both).not.toContain('Ship the decision');
+});
+
+test('a word that is in most documents cannot win on its own', () => {
+  const crowd = [quiet('Marks all done'), ...Array.from({ length: 8 }, (_, index) => quiet(`Todo note ${index}`))];
+  const list = rank(crowd, 'complete the todo').map((hit) => hit.doc.title);
+  expect(list[0]).toBe('Marks all done');
+});