kryptheon 0.1.9 → 0.1.11

package/kryptheon-cleanup.js

@@ -0,0 +1,245 @@
+// Taking the fumbling out of a recording before it becomes a baseline.
+//
+// Codegen records every keystroke, including the wrong ones. A username typed
+// once with a typo and again correctly comes out as two fills of the same box:
+//
+//   await page.getByRole('textbox', { name: 'Username' }).fill('shantanu892');
+//   await page.getByRole('textbox', { name: 'Username' }).fill('shantanu89');
+//
+// Kept as-is, that is not a tidiness problem. The first fill is a whole wrong
+// login attempt performed on every run from then on, and the mistake is baked
+// into the baseline as if it were the intended flow.
+//
+// The same happens with a stray click on nothing - getByRole('img') with no
+// name and no text identifies nothing, and clicking it does nothing - and with
+// the same button clicked twice because the first one seemed not to take.
+//
+// Everything here follows one rule: when in doubt, keep it. Leaving a pointless
+// step in a recording costs a moment. Removing a real one silently changes what
+// the test does, and nobody finds out until the thing it was covering breaks
+// unnoticed. So every removal below needs the steps to be adjacent, to be the
+// same action on the same element, and to have nothing between them - anything
+// less certain is left alone.
+//
+// Pure string work: no Playwright, no filesystem.
+
+const selectors = require('./kryptheon-selectors.js');
+
+/* --------------------------------------------------------------------------
+   Reading the recording as steps.
+-------------------------------------------------------------------------- */
+
+// Only the things a person does to the page.
+//
+// Assertions end in toBeVisible, toHaveText and the like, none of which are
+// here, so an assertion is never read as a step in the first place. There was
+// an explicit guard against them as well; mutation testing showed removing it
+// changed nothing, and a line that reads like the reason something is safe -
+// while not being the reason - is worse than no line at all. This list is the
+// reason. Anything added to it has to be a thing a person actually did.
+const ACTION = /\.\s*(click|dblclick|fill|type|press|check|uncheck|selectOption|hover|tap|setInputFiles|clear|goto)\s*\(/;
+
+/**
+ * Every line that does something to the page, with the parts that matter.
+ *
+ * `chain` is how the element was found, which is what makes two steps "the
+ * same element". It comes from the same reader the fragile-selector report
+ * uses, so the two can never disagree about what a step points at.
+ */
+function readSteps(source) {
+  const steps = [];
+  String(source || '')
+    .split('\n')
+    .forEach((raw, i) => {
+      const line = raw.trim();
+      if (!/\bpage\s*\./.test(line)) return;
+      const match = line.match(ACTION);
+      if (!match) return;
+      steps.push({
+        line: i + 1,
+        text: line,
+        action: match[1],
+        chain: selectors.selectorChain(line),
+      });
+    });
+  return steps;
+}
+
+/** The readable name of the thing a step acts on, for saying what went. */
+function labelFor(chain) {
+  const text = String(chain || '');
+  let m = text.match(/name:\s*(['"])(.*?)\1/);
+  if (m) return m[2];
+  m = text.match(/getBy(?:Label|Placeholder|Text|TestId|Title|AltText)\(\s*(['"])(.*?)\1/);
+  if (m) return m[2];
+  m = text.match(/getByRole\(\s*(['"])(.*?)\1/);
+  if (m) return 'the ' + m[2];
+  m = text.match(/locator\(\s*(['"])(.*?)\1/);
+  if (m) return m[2];
+  return 'it';
+}
+
+/* --------------------------------------------------------------------------
+   A step that points at nothing.
+-------------------------------------------------------------------------- */
+
+// Anything that says which element is meant. One of these present is enough
+// for a step to be left alone.
+const IDENTIFYING = /name\s*:|getByLabel|getByPlaceholder|getByTestId|getByTitle|getByAltText|getByText/;
+
+// What a .filter({ hasText: ... }) is matching on, if anything.
+const HAS_TEXT = /has(?:Not)?Text\s*:\s*(\/(?:\\.|[^/\\])*\/[a-z]*|(['"])(?:\\.|(?!\2).)*\2)/;
+
+/**
+ * Whether a text filter actually narrows anything down.
+ *
+ * `hasText: /^$/` is the one codegen writes when there was no text to match
+ * on - it says "an element with empty text", which is every empty element on
+ * the page. Written out as a test rather than folded into the pattern above,
+ * because a lookahead there can slide along and match at the space instead,
+ * which quietly reads an empty filter as identifying.
+ */
+function narrowsAnything(chain) {
+  const m = String(chain || '').match(HAS_TEXT);
+  if (!m) return false;
+  const value = m[1];
+  if (value[0] !== '/') return value.length > 2; // a non-empty string
+  const body = value.slice(1, value.lastIndexOf('/'));
+  return body !== '' && body !== '^$';
+}
+
+// A CSS selector that picks something out: an id, a class, an attribute.
+const ANCHORED = /locator\(\s*(['"])[^'"]*[#.\[][^'"]*\1/;
+
+// Roles that are not there to be used. A click on one of these does nothing,
+// which is why codegen only ever writes them by accident. Interactive roles -
+// button, link, textbox - are deliberately absent even when unnamed: an
+// unnamed button is still a button, and removing a click on one would change
+// what the recording does.
+const INERT_ROLE = /getByRole\(\s*(['"])(img|image|generic|presentation|none|paragraph|separator|figure)\1/;
+
+/**
+ * A click on something with nothing to identify it.
+ *
+ * Both halves are required: the step must name nothing at all, and the element
+ * must be of a kind that does nothing when clicked. Either one on its own is
+ * not enough to be sure.
+ */
+function pointsAtNothing(step) {
+  if (!step || step.action !== 'click') return false;
+  const chain = step.chain;
+  if (IDENTIFYING.test(chain)) return false;
+  if (narrowsAnything(chain)) return false;
+  if (ANCHORED.test(chain)) return false;
+  return INERT_ROLE.test(chain);
+}
+
+/* --------------------------------------------------------------------------
+   The clean-up.
+-------------------------------------------------------------------------- */
+
+/**
+ * The steps to take out, and why, in the words they will be reported in.
+ *
+ * Nothing here looks at the values that were typed. They are not needed to
+ * decide anything, and by this point a password may already have been moved
+ * into an environment variable - printing "typed X then Y" would put the very
+ * thing that was just hidden back on the screen.
+ */
+function findRedundantSteps(source) {
+  const steps = readSteps(source);
+  const removals = [];
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const next = steps[i + 1];
+
+    if (pointsAtNothing(step)) {
+      removals.push({
+        line: step.line,
+        text: step.text,
+        kind: 'points-at-nothing',
+        why: 'a click on something with nothing to identify it',
+      });
+      continue;
+    }
+
+    if (!next || next.chain !== step.chain || step.action === 'goto') continue;
+
+    // Adjacent in the list, so nothing happened in between. A fill with
+    // another action between it and the next one is somebody going back to a
+    // field on purpose, and both are kept.
+    if (step.action === 'fill' && next.action === 'fill') {
+      removals.push({
+        line: step.line,
+        text: step.text,
+        kind: 'typed-twice',
+        why: labelFor(step.chain) + ' was typed twice in a row, and only the last one counts',
+      });
+      continue;
+    }
+
+    if (step.action === 'click' && next.action === 'click') {
+      // The second click is the one dropped: the first is what the person
+      // meant to do, and it is the one whose effect the rest of the recording
+      // was made against.
+      removals.push({
+        line: next.line,
+        text: next.text,
+        kind: 'clicked-twice',
+        why: labelFor(step.chain) + ' was clicked twice in a row, and once is enough',
+      });
+      i++;
+    }
+  }
+
+  return removals;
+}
+
+/**
+ * The recording with the fumbling taken out.
+ *
+ * Lines are removed by number and nothing else is touched, so what comes back
+ * is the file as it was minus whole lines - never reformatted, never rewritten.
+ */
+function cleanRecording(source) {
+  const text = String(source || '');
+  const removed = findRedundantSteps(text);
+  if (!removed.length) return { source: text, removed: [] };
+
+  const drop = new Set(removed.map((r) => r.line));
+  const kept = text.split('\n').filter((line, i) => !drop.has(i + 1));
+  return { source: kept.join('\n'), removed: removed };
+}
+
+/**
+ * What was taken out, said plainly.
+ *
+ * Never silent about it. A tool that edits what you recorded and does not say
+ * so is worse than one that leaves the mess in - the next time the recording
+ * does something unexpected, you have no way of knowing it was changed.
+ */
+function describeCleanup(removed) {
+  const list = removed || [];
+  if (!list.length) return [];
+
+  const lines = [];
+  lines.push('');
+  lines.push(
+    '  ' + list.length + (list.length === 1 ? ' step was' : ' steps were') + ' taken out of the recording:',
+  );
+  for (const item of list) lines.push('    - ' + item.why);
+  lines.push('');
+  lines.push('  Everything else was left exactly as you did it.');
+  lines.push('');
+  return lines;
+}
+
+module.exports = {
+  readSteps: readSteps,
+  findRedundantSteps: findRedundantSteps,
+  cleanRecording: cleanRecording,
+  describeCleanup: describeCleanup,
+  pointsAtNothing: pointsAtNothing,
+  labelFor: labelFor,
+};

package/kryptheon-fixture.js

@@ -20,7 +20,8 @@ const base = require('@playwright/test');
 // Reuse the reporter's host-stripping so a baseline stores exactly the shape
 // the reporter prints.
 const { requestPath } = require('./kryptheon-reporter.js');
-const signature = require('./kryptheon-signature.js');
+const signature = require('./kryptheon-signature.js');
+const replay = require('./kryptheon-replay.js');
 
 const MAX_ITEMS = 5; // keep the failure block readable
 
@@ -128,6 +129,10 @@ function normalisedEntry(current) {
   // Only when there is one. A run whose capture failed must not write an empty
   // signature over a good one, or the next run would report everything as gone.
   if (current.signature) stored.signature = current.signature;
+  // What recording this was taken from. Without it, a saved result is tied
+  // only to a file name, and a re-recording that lands on the same name
+  // inherits a baseline it never created and can never match.
+  if (current.recordingId) stored.recordingId = current.recordingId;
   return stored;
 }
 
@@ -232,6 +237,17 @@ function newObservations(current, previous) {
 // Adds a signature to an accepted baseline that predates the feature, without
 // touching anything else about it - including when it was recorded, which is
 // what the failure report means by "this last worked at".
+// Ties a saved result written before fingerprints existed to the recording it
+// is now being compared against. Only ever on a pass, so an entry is never
+// bound to a run that did not match it.
+function stampRecording(file, key, recordingId) {
+  const all = readBaselines(file);
+  const entry = all[key];
+  if (!entry || typeof entry !== 'object' || entry.recordingId || !recordingId) return false;
+  entry.recordingId = recordingId;
+  return saveBaselines(file, all);
+}
+
 function upgradeBaseline(file, key, sig) {
   const all = readBaselines(file);
   const entry = all[key];
@@ -247,6 +263,17 @@ function applyBaseline(file, key, current) {
     writeBaseline(file, key, current);
     return { status: 'created', message: null };
   }
+
+  // A saved result taken from a different recording describes a page this
+  // flow never visited. Comparing against it produces a failure on the first
+  // run that no amount of fixing the app can clear, so it is replaced rather
+  // than argued with. Only when both fingerprints are known: an entry from
+  // before they existed is left alone, because "cannot tell" must never
+  // become "accept whatever this run saw".
+  if (previous.recordingId && current.recordingId && previous.recordingId !== current.recordingId) {
+    writeBaseline(file, key, current);
+    return { status: 'created', message: null };
+  }
   const message = compareBaselines(previous, current);
   if (message) return { status: 'changed', message: message };
 
@@ -257,6 +284,10 @@ function applyBaseline(file, key, current) {
     upgradeBaseline(file, key, current.signature);
     return { status: 'learned', message: null };
   }
+  if (!previous.recordingId && current.recordingId) {
+    stampRecording(file, key, current.recordingId);
+    return { status: 'learned', message: null };
+  }
   return { status: 'match', message: null };
 }
 
@@ -283,6 +314,17 @@ const test = base.test.extend({
 
     const key = baselineKey(testInfo.file, testInfo.title);
 
+    // The steps this recording actually performs. Comments, blank lines and
+    // the test name are ignored, so tidying a file does not read as a
+    // different recording - only changing what it does.
+    const recordingId = (function () {
+      try {
+        return replay.recordingId(fs.readFileSync(testInfo.file, 'utf8'));
+      } catch (e) {
+        return null;
+      }
+    })();
+
     // Reports only what this run added on top of the last passing run.
     const attachObservations = async () => {
       let url = null;
@@ -351,6 +393,7 @@ const test = base.test.extend({
         consoleErrors: consoleErrors,
         failedRequests: failedRequests,
         signature: captured,
+        recordingId: recordingId,
       };
     } catch (e) {
       current = null; // page closed by the test - leave any baseline untouched
@@ -384,5 +427,6 @@ module.exports = {
   compareBaselines: compareBaselines,
   applyBaseline: applyBaseline,
   upgradeBaseline: upgradeBaseline,
+  stampRecording: stampRecording,
   BASELINE_FILE: BASELINE_FILE,
 };

package/kryptheon-project.js

@@ -0,0 +1,199 @@
+// Working out whether this folder is a project at all.
+//
+// `kryptheon check` reads recordings out of ./tests and baselines out of the
+// folder it was run in. Run it somewhere that is not a project - a home folder,
+// the place a global install happened to leave you - and it will happily find
+// whatever tests/ happens to be lying around and run those instead, reporting
+// results for a project nobody asked about. That has already happened to
+// somebody who installed into their home folder.
+//
+// Quietly testing the wrong project is the worst thing this tool can do. A
+// green that belongs to something else is not a result, it is a lie with a tick
+// next to it. So the answer to "is this a project?" has to be settled before
+// anything runs, and the answer has to be a stop rather than a guess.
+//
+// Pure path work: nothing here runs a test or reads a recording.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// For someone who genuinely keeps recordings outside a package. Deliberately
+// long-winded: it should be something you decide to type, not something you
+// stumble into.
+const ESCAPE_HATCH = 'KRYPTHEON_ALLOW_NO_PACKAGE_JSON';
+
+function hasPackageJson(dir) {
+  try {
+    return fs.statSync(path.join(dir, 'package.json')).isFile();
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * One comparable form of a path.
+ *
+ * The trailing separator has to go or C:\Users and C:\Users\ never match, but
+ * it must not be taken off before the root test below. "C:" without a separator
+ * is not the drive - Node resolves it to the current directory - so a root
+ * compared in this form would quietly become "wherever I happen to be".
+ */
+function tidy(dir) {
+  return path.resolve(String(dir || '')).replace(/[\\/]+$/, '').toLowerCase();
+}
+
+/** The folders that are somebody's whole account or the machine itself. */
+function isHomeOrSystem(dir) {
+  // A drive or filesystem root: C:\, D:\, /. Done on the resolved path, with
+  // its separator still on, for the reason above.
+  const resolved = path.resolve(String(dir || ''));
+  if (resolved === path.parse(resolved).root) return true;
+
+  const here = tidy(dir);
+  if (here === tidy(os.homedir())) return true;
+
+  for (const candidate of systemFolders()) {
+    if (here === tidy(candidate)) return true;
+  }
+  return false;
+}
+
+/**
+ * Every folder that belongs to the machine or to an account rather than to a
+ * project, resolved.
+ *
+ * The first two entries are derived from the running system; the literals after
+ * them are fallbacks for the usual layouts. They overlap - on Windows
+ * USERPROFILE is the home folder and "/Users" resolves to C:\Users - and the
+ * overlap is deliberate: a machine whose home is somewhere unusual is covered
+ * by the derived pair, and a machine whose environment is missing entries is
+ * covered by the literals.
+ */
+function systemFolders() {
+  return [
+    // The folder every account lives in - C:\Users, /home, /Users. On its own
+    // it has no package.json so it would be refused anyway, but one stray npm
+    // install there and it would look exactly like a project.
+    path.dirname(os.homedir()),
+    process.env.SystemRoot,
+    process.env.ProgramFiles,
+    process.env['ProgramFiles(x86)'],
+    process.env.ProgramData,
+    process.env.APPDATA,
+    process.env.LOCALAPPDATA,
+    process.env.USERPROFILE,
+    '/root',
+    '/home',
+    '/Users',
+    '/usr',
+    '/etc',
+    '/bin',
+    '/var',
+    '/opt',
+  ].filter(Boolean);
+}
+
+/**
+ * Whether this folder can be checked, and if not, why not.
+ *
+ * `allowed` is the escape hatch having been set. It is reported rather than
+ * hidden, so a run that only worked because of it says so.
+ */
+function inspectProject(dir, env) {
+  const environment = env || process.env;
+  const allowed = String(environment[ESCAPE_HATCH] || '') !== '';
+  const packaged = hasPackageJson(dir);
+  const personal = isHomeOrSystem(dir);
+  const base = { dir: dir, packaged: packaged, personal: personal, allowed: allowed };
+
+  if (allowed) return Object.assign({ ok: true, reason: null }, base);
+
+  // A home folder is refused even when it has a package.json, and this is not
+  // belt and braces - it is the case that actually happened. Someone installed
+  // the tool into their home folder, so npm left a package.json and a
+  // node_modules there, and a tests folder alongside them. Every sign this
+  // could look for says "project"; none of them is true. The measured state of
+  // one real machine: C:\Users\<name> holding package.json, node_modules and
+  // tests, none of which belong to anything.
+  if (personal) return Object.assign({ ok: false, reason: 'personal' }, base);
+  if (!packaged) return Object.assign({ ok: false, reason: 'no-package' }, base);
+  return Object.assign({ ok: true, reason: null }, base);
+}
+
+/**
+ * Why this folder is not a project, and what to do instead.
+ *
+ * The folder is printed back because the commonest version of this is not
+ * knowing where you are - a new terminal, a global install, a shell that opened
+ * somewhere else.
+ */
+function noProjectLines(inspection) {
+  const lines = [''];
+
+  if (inspection.personal) {
+    lines.push('  This is your home or a system folder, not a project.');
+    lines.push('');
+    lines.push('  You are in:  ' + inspection.dir);
+    lines.push('');
+    // Almost never deliberate, and the one place where running anyway does the
+    // most damage. Said explicitly because a home folder that has had anything
+    // installed into it looks exactly like a project from the outside.
+    lines.push('  Recordings and results are kept beside the app they belong to,');
+    lines.push('  so running here would check whichever tests folder happens to be');
+    lines.push('  sitting in this one - almost certainly not the one you meant.');
+    if (inspection.packaged) {
+      lines.push('');
+      // Said plainly, because otherwise the package.json sitting right there
+      // makes this message look like the bug rather than the diagnosis.
+      lines.push('  There is a package.json here, but that is not what makes a project.');
+      lines.push('  It looks like npm install was run in this folder by mistake, which');
+      lines.push('  leaves a package.json and a node_modules behind.');
+    }
+    lines.push('');
+  } else {
+    lines.push('  There is no project here - this folder has no package.json.');
+    lines.push('');
+    lines.push('  You are in:  ' + inspection.dir);
+    lines.push('');
+  }
+
+  lines.push('  Change into your project folder and run this again:');
+  lines.push('');
+  lines.push('    cd path\\to\\your\\project');
+  lines.push('    kryptheon check');
+  lines.push('');
+  lines.push('  If you really do keep recordings outside a package, set');
+  lines.push('  ' + ESCAPE_HATCH + '=1 and this will run anyway.');
+  lines.push('');
+  return lines;
+}
+
+/** A real project, with nothing recorded in it yet. */
+function noRecordingsLines() {
+  return [
+    '',
+    '  No recordings were found in this project.',
+    '',
+    '  This is not a failure, and there is nothing in the code to fix.',
+    '',
+    '  Record a flow through your app first:',
+    '',
+    '    kryptheon record http://localhost:3000',
+    '',
+    '  That opens a browser window, so it has to be run by a person in a',
+    '  normal terminal - it cannot be done from an AI assistant.',
+    '',
+  ];
+}
+
+module.exports = {
+  ESCAPE_HATCH: ESCAPE_HATCH,
+  hasPackageJson: hasPackageJson,
+  systemFolders: systemFolders,
+  tidy: tidy,
+  isHomeOrSystem: isHomeOrSystem,
+  inspectProject: inspectProject,
+  noProjectLines: noProjectLines,
+  noRecordingsLines: noRecordingsLines,
+};

package/kryptheon-recordings.js

@@ -0,0 +1,149 @@
+// Telling apart the two things a red line can mean.
+//
+// A recording that used to pass and now does not is a regression: something
+// changed and it is worth looking at. A recording that has never passed once is
+// not a regression - there is nothing to regress from. Usually it was made
+// while learning the tool, or it contains a step that cannot happen twice.
+//
+// Counting them together is what makes the first day miserable. Someone records
+// three or four flows while working out what this is, runs check, and reads
+// "2 working, 4 broken" - so the tool looks like it is reporting four faults in
+// an app that is fine. Nothing is broken. Four recordings simply never had a
+// baseline.
+//
+// Pure string and number work: no filesystem, no Playwright, so the reporter,
+// the command line and the unit checks all use the same rules.
+
+/**
+ * How a run actually went, in the three states that mean different things.
+ *
+ * `unproven` is deliberately not folded into `broken`. It is the whole point.
+ */
+function summarise(records) {
+  const list = records || [];
+  let working = 0;
+  let broken = 0;
+  let unproven = 0;
+
+  for (const record of list) {
+    if (!record) continue;
+    if (record.status === 'passed') {
+      working++;
+    } else if (record.status === 'failed') {
+      if (record.neverPassed) unproven++;
+      else broken++;
+    }
+  }
+  return { working: working, broken: broken, unproven: unproven };
+}
+
+function plural(n, word) {
+  return n + ' ' + word + (n === 1 ? '' : 's');
+}
+
+/**
+ * The lines that explain a set of recordings that have never passed.
+ *
+ * Said as a state of the recordings rather than a fault in the app, because
+ * that is what it is, and because the reader's next move is to make each one
+ * pass once - not to go looking through their code.
+ */
+function unprovenLines(count) {
+  if (!count) return [];
+  const is = count === 1 ? 'has' : 'have';
+  const it = count === 1 ? 'it' : 'they';
+  return [
+    plural(count, 'recording') + ' ' + is + ' no baseline yet - ' + it + ' ' + is + ' never passed.',
+    'Each one has to pass once before it can tell you anything. Until then',
+    'nothing is known to be broken.',
+  ];
+}
+
+/**
+ * The summary at the end of a run, in two parts when the second part applies.
+ *
+ * The first line only ever counts recordings that once worked, so a green
+ * "0 broken" stays honest: it means nothing regressed, and the line underneath
+ * says what is still unproven rather than hiding it.
+ */
+function summaryLines(counts) {
+  const c = counts || { working: 0, broken: 0, unproven: 0 };
+  const lines = ['Summary: ' + c.working + ' working, ' + c.broken + ' broken.'];
+  for (const line of unprovenLines(c.unproven)) lines.push(line);
+  return lines;
+}
+
+/**
+ * The baseline keys belonging to one recording file.
+ *
+ * Baselines are keyed "tests/thing.spec.js :: Title", so removing a recording
+ * without removing these would leave the saved results of a file that is no
+ * longer there.
+ */
+function baselineKeysForSpec(baselines, specPath) {
+  const wanted = String(specPath || '').split('\\').join('/');
+  if (!wanted) return [];
+  return Object.keys(baselines || {}).filter((key) => {
+    const file = String(key).split(' :: ')[0].split('\\').join('/');
+    return file === wanted;
+  });
+}
+
+/**
+ * What a person meant by their answer to a numbered list.
+ *
+ * Accepts a number, a file name, "all", or nothing at all. Anything else is
+ * reported as not understood rather than guessed at - these answers delete
+ * files, so a near-miss must never be treated as a choice.
+ */
+function chooseFromList(names, answer) {
+  const list = names || [];
+  const said = String(answer == null ? '' : answer).trim();
+  if (!said) return { action: 'cancel' };
+  if (/^(a|all)$/i.test(said)) return { action: 'remove', names: list.slice() };
+
+  if (/^\d+$/.test(said)) {
+    const index = Number(said);
+    if (index < 1 || index > list.length) {
+      return { action: 'unclear', said: said, why: 'there is no recording numbered ' + index };
+    }
+    return { action: 'remove', names: [list[index - 1]] };
+  }
+
+  const lower = said.toLowerCase();
+  const matches = list.filter((name) => {
+    const n = String(name).toLowerCase();
+    return n === lower || n === lower + '.spec.js' || n.replace(/\.spec\.js$/, '') === lower;
+  });
+  if (matches.length === 1) return { action: 'remove', names: matches };
+  if (matches.length > 1) {
+    return { action: 'unclear', said: said, why: 'more than one recording is called that' };
+  }
+  return { action: 'unclear', said: said, why: 'there is no recording called that' };
+}
+
+/**
+ * What to ask when a project already has recordings and another is starting.
+ *
+ * Keeping is the default because it is the answer that cannot lose work.
+ */
+function existingRecordingsQuestion(count) {
+  return [
+    '',
+    '  This project already has ' + plural(count, 'recording') + '.',
+    '',
+    '    k  keep them, and add this new one   (default)',
+    '    r  replace them - delete ' + (count === 1 ? 'it' : 'all ' + count) + ' and keep only this one',
+    '',
+  ];
+}
+
+module.exports = {
+  summarise: summarise,
+  summaryLines: summaryLines,
+  unprovenLines: unprovenLines,
+  baselineKeysForSpec: baselineKeysForSpec,
+  chooseFromList: chooseFromList,
+  existingRecordingsQuestion: existingRecordingsQuestion,
+  plural: plural,
+};