@meza/adr-tools 1.0.10 → 1.0.12

package/src/lib/adr.ts

@@ -1,13 +1,15 @@
-import { newNumber } from './numbering';
-import { template } from './template';
-import fs from 'fs/promises';
-import path from 'path';
-import { getDir, workingDir } from './config';
-import { prompt } from 'inquirer';
-import chalk from 'chalk';
-import { getTitleFrom, injectLink, supersede } from './manipulator';
-import { findMatchingFilesFor, getLinkDetails } from './links';
 import childProcess from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import fs from 'fs/promises';
+import { getDir, workingDir } from './config.js';
+import { findMatchingFilesFor, getLinkDetails } from './links.js';
+import { getTitleFrom, injectLink, supersede } from './manipulator.js';
+import { newNumber } from './numbering.js';
+import { askForClarification } from './prompt.js';
+import { template } from './template.js';
+
+const __filename = fileURLToPath(import.meta.url);
 
 interface NewOptions {
   supersedes?: string[];
@@ -17,18 +19,6 @@ interface NewOptions {
   links?: string[];
 }
 
-const askForClarification = async (searchString: string, matches: string[]) => {
-  const selection = await prompt([
-    {
-      type: 'list',
-      name: 'target',
-      message: `Which file do you want to link to for ${chalk.blue(searchString)}?`,
-      choices: matches
-    }
-  ]);
-  return selection.target;
-};
-
 // eslint-disable-next-line no-unused-vars
 enum LinkType {
   // eslint-disable-next-line no-unused-vars
@@ -51,14 +41,21 @@ const actuallyLink = async (task: LinkTask) => {
   const oldAdrContent = await fs.readFile(linkedFile, 'utf8');
   const oldTitle = getTitleFrom(oldAdrContent);
   const newTitle = getTitleFrom(newAdrContent);
-  let dirtyOld = '', dirtyNew = '';
+  let dirtyOld = '',
+    dirtyNew = '';
   switch (task.type) {
     case LinkType.LINK:
-      dirtyOld = injectLink(oldAdrContent, `${task.reverseLink} [${newTitle}](${path.relative(await getDir(), task.sourcePath)})`);
+      dirtyOld = injectLink(
+        oldAdrContent,
+        `${task.reverseLink} [${newTitle}](${path.relative(await getDir(), task.sourcePath)})`
+      );
       dirtyNew = injectLink(newAdrContent, `${task.link} [${oldTitle}](${task.targetPath})`);
       break;
     case LinkType.SUPERSEDE:
-      dirtyOld = supersede(oldAdrContent, `${task.reverseLink} [${newTitle}](${path.relative(await getDir(), task.sourcePath)})`);
+      dirtyOld = supersede(
+        oldAdrContent,
+        `${task.reverseLink} [${newTitle}](${path.relative(await getDir(), task.sourcePath)})`
+      );
       dirtyNew = injectLink(newAdrContent, `${task.link} [${oldTitle}](${task.targetPath})`);
       break;
     default:
@@ -69,11 +66,7 @@ const actuallyLink = async (task: LinkTask) => {
   await fs.writeFile(task.sourcePath, dirtyNew);
 };
 
-const processSupersedes = async (
-  sourcePath: string,
-  supersedes: string[] = [],
-  suppressPrompts: boolean = false
-) => {
+const processSupersedes = async (sourcePath: string, supersedes: string[] = [], suppressPrompts: boolean = false) => {
   if (supersedes.length === 0) {
     return;
   }
@@ -91,22 +84,19 @@ const processSupersedes = async (
 
     if (targetDetails.matches.length > 1) {
       if (suppressPrompts) {
-        throw new Error(`Multiple files match the search pattern for "${targetDetails.original}".\n`
-          + 'Please specify which file you want to targetDetails to more or remove the -q or --quiet options from the command line.');
-      } else {
-        task.targetPath = await askForClarification(targetDetails.original, targetDetails.matches);
+        throw new Error(
+          `Multiple files match the search pattern for "${targetDetails.original}".\n` +
+            'Please specify which file you want to targetDetails to more or remove the -q or --quiet options from the command line.'
+        );
       }
+      task.targetPath = await askForClarification(targetDetails.original, targetDetails.matches);
     }
 
     await actuallyLink(task);
   }
 };
 
-const injectLinksTo = async (
-  sourcePath: string,
-  links: string[] = [],
-  suppressPrompts: boolean = false
-) => {
+const injectLinksTo = async (sourcePath: string, links: string[] = [], suppressPrompts: boolean = false) => {
   if (links.length === 0) {
     return;
   }
@@ -124,23 +114,22 @@ const injectLinksTo = async (
 
     if (targetDetails.matches.length > 1) {
       if (suppressPrompts) {
-        throw new Error(`Multiple files match the search pattern for "${targetDetails.original}".\n`
-          + 'Please specify which file you want to targetDetails to more or remove the -q or --quiet options from the command line.');
-      } else {
-        task.targetPath = await askForClarification(targetDetails.original, targetDetails.matches);
+        throw new Error(
+          `Multiple files match the search pattern for "${targetDetails.original}".\n` +
+            'Please specify which file you want to targetDetails to more or remove the -q or --quiet options from the command line.'
+        );
       }
+      task.targetPath = await askForClarification(targetDetails.original, targetDetails.matches);
     }
 
     await actuallyLink(task);
   }
-
 };
 //Generate a table of contents for the adr directory
-export const generateToc = async (options?: {prefix?: string}) => {
-
+export const generateToc = async (options?: { prefix?: string }) => {
   const adrDir = await getDir();
   const files = await fs.readdir(adrDir);
-  const toc = files.filter((file) => file.match(/^\d{4}-.*\.md$/));
+  const toc = files.filter((file) => file.match(/^\d{4}-.*\.md$/)).sort();
 
   const titles = toc.map(async (file) => {
     const title = getTitleFrom(await fs.readFile(path.join(adrDir, file), 'utf8'));
@@ -157,27 +146,26 @@ export const newAdr = async (title: string, config?: NewOptions) => {
   const newNum = await newNumber();
   const formattedDate = config?.date || new Date().toISOString().split('T')[0] || 'ERROR';
   const tpl = await template(config?.template);
-  const adr = tpl.replace('DATE', formattedDate).replace('TITLE', title).replace('NUMBER', newNum.toString()).replace('STATUS', 'Accepted');
+  const adr = tpl
+    .replace('DATE', formattedDate)
+    .replace('TITLE', title)
+    .replace('NUMBER', newNum.toString())
+    .replace('STATUS', 'Accepted');
   const paddedNumber = newNum.toString().padStart(4, '0');
-  const cleansedTitle = title.toLowerCase().replace(/\W/g, '-').replace(/^(.*)\W$/, '$1').replace(/^\W(.*)$/, '$1');
+  const cleansedTitle = title
+    .toLowerCase()
+    .replace(/\W/g, '-')
+    .replace(/^(.*)\W$/, '$1')
+    .replace(/^\W(.*)$/, '$1');
   const fileName = `${paddedNumber}-${cleansedTitle}.md`;
   const adrDirectory = await getDir();
   const adrPath = path.resolve(path.join(adrDirectory, fileName));
   await fs.writeFile(adrPath, adr);
   await fs.writeFile(path.resolve(adrDirectory, '.adr-sequence.lock'), newNum.toString());
 
-  await processSupersedes(
-    adrPath,
-    config?.supersedes,
-    config?.suppressPrompts
-  );
-  await injectLinksTo(
-    adrPath,
-    config?.links,
-    config?.suppressPrompts
-  );
+  await processSupersedes(adrPath, config?.supersedes, config?.suppressPrompts);
+  await injectLinksTo(adrPath, config?.links, config?.suppressPrompts);
   await generateToc();
-  const newAdrPath = path.relative(workingDir(), adrPath);
 
   if (process.env.VISUAL) {
     await childProcess.spawn(process.env.VISUAL, [adrPath], {
@@ -193,12 +181,10 @@ export const newAdr = async (title: string, config?: NewOptions) => {
     });
     return;
   }
-  console.log(newAdrPath);
-
 };
 
 export const init = async (directory?: string) => {
-  const dir = directory || await getDir();
+  const dir = directory || (await getDir());
   await fs.mkdir(dir, { recursive: true });
   await fs.writeFile(path.join(workingDir(), '.adr-dir'), path.relative(workingDir(), dir));
   await newAdr('Record Architecture Decisions', {
@@ -207,7 +193,13 @@ export const init = async (directory?: string) => {
   });
 };
 
-export const link = async (source: string, link: string, target: string, reverseLink: string, options?: {quiet?: boolean}) => {
+export const link = async (
+  source: string,
+  link: string,
+  target: string,
+  reverseLink: string,
+  options?: { quiet?: boolean }
+) => {
   const getFor = async (pattern: string) => {
     const found = await findMatchingFilesFor(pattern);
     if (found.length === 1) {
@@ -215,8 +207,10 @@ export const link = async (source: string, link: string, target: string, reverse
     }
 
     if (options?.quiet) {
-      throw new Error(`Multiple files match the search pattern for "${pattern}".\n`
-        + 'Please specify which file you want to targetDetails to more or remove the -q or --quiet options from the command line.');
+      throw new Error(
+        `Multiple files match the search pattern for "${pattern}".\n` +
+          'Please specify which file you want to targetDetails to more or remove the -q or --quiet options from the command line.'
+      );
     }
 
     return askForClarification(pattern, found);
@@ -225,18 +219,19 @@ export const link = async (source: string, link: string, target: string, reverse
   const sourceFile = await getFor(source);
 
   await injectLinksTo(path.resolve(await getDir(), sourceFile), [`${target}:${link}:${reverseLink}`]);
-
 };
 
 export const listAdrs = async () => {
   const dir = await getDir();
   const files = await fs.readdir(dir);
-  const toc = files.map(f => {
-    const adrFile = f.match(/^0*(\d+)-.*$/);
-    if (adrFile) {
-      return path.resolve(dir, adrFile[0]);
-    }
-    return '';
-  }).filter(f => f !== '');
+  const toc = files
+    .map((f) => {
+      const adrFile = f.match(/^0*(\d+)-.*$/);
+      if (adrFile) {
+        return path.resolve(dir, adrFile[0]);
+      }
+      return '';
+    })
+    .filter((f) => f !== '');
   return toc;
 };

package/src/lib/config.ts

@@ -1,6 +1,6 @@
-import fs from 'fs/promises';
 import { constants } from 'fs';
 import path from 'path';
+import fs from 'fs/promises';
 
 export const workingDir = () => process.cwd();
 
@@ -8,7 +8,7 @@ const findTopLevelDir = async (dir: string): Promise<string> => {
   try {
     await fs.access(path.join(dir, '.adr-dir'), constants.F_OK);
     return dir;
-  } catch (e) {
+  } catch (_e) {
     if (dir === '/') {
       throw new Error('No ADR directory config found');
     }
@@ -22,7 +22,7 @@ const getDirPath = async (): Promise<string> => {
     const configDir = await findTopLevelDir(workingDir());
     const configFile = await fs.readFile(path.join(configDir, '.adr-dir'), 'utf8');
     return path.relative(workingDir(), path.join(configDir, configFile.trim()));
-  } catch (e) {
+  } catch (_e) {
     return path.resolve(path.join(workingDir(), 'doc/adr'));
   }
 };

package/src/lib/links.test.ts

@@ -1,9 +1,9 @@
-import { vi, describe, it, expect, afterEach } from 'vitest';
 import fs from 'fs/promises';
-import { getDir } from './config';
-import { getLinkDetails } from './links';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getDir } from './config.js';
+import { getLinkDetails } from './links.js';
 
-vi.mock('./config');
+vi.mock('./config.js');
 vi.mock('fs/promises');
 
 describe('The link lib', () => {
@@ -27,11 +27,7 @@ describe('The link lib', () => {
 
   it('does handles multiple matches', async () => {
     vi.mocked(getDir).mockResolvedValueOnce('/');
-    vi.mocked(fs.readdir).mockResolvedValueOnce([
-      '1-one',
-      '1-two',
-      '1-three'
-    ] as any);
+    vi.mocked(fs.readdir).mockResolvedValueOnce(['1-one', '1-two', '1-three'] as any);
     const linkString = '1:overrides:overriden by';
     const response = await getLinkDetails(linkString);
     expect(response).toEqual({
@@ -39,21 +35,13 @@ describe('The link lib', () => {
       original: '1:overrides:overriden by',
       link: 'overrides',
       reverseLink: 'overriden by',
-      matches: [
-        '1-one',
-        '1-two',
-        '1-three'
-      ]
+      matches: ['1-one', '1-two', '1-three']
     });
   });
 
   it('returns only files that match the pattern', async () => {
     vi.mocked(getDir).mockResolvedValueOnce('/');
-    vi.mocked(fs.readdir).mockResolvedValueOnce([
-      'on1e',
-      '1-two',
-      'three'
-    ] as any);
+    vi.mocked(fs.readdir).mockResolvedValueOnce(['on1e', '1-two', 'three'] as any);
     const linkString = '1:overrides:overriden by';
     const response = await getLinkDetails(linkString);
     expect(response).toEqual({
@@ -61,10 +49,7 @@ describe('The link lib', () => {
       original: '1:overrides:overriden by',
       link: 'overrides',
       reverseLink: 'overriden by',
-      matches: [
-        'on1e',
-        '1-two'
-      ]
+      matches: ['on1e', '1-two']
     });
   });
 
@@ -82,5 +67,4 @@ describe('The link lib', () => {
       matches: []
     });
   });
-
 });

package/src/lib/links.ts

@@ -1,5 +1,5 @@
 import fs from 'fs/promises';
-import { getDir } from './config';
+import { getDir } from './config.js';
 
 export interface LinkDetails {
   pattern: string;
@@ -11,7 +11,7 @@ export interface LinkDetails {
 
 export const findMatchingFilesFor = async (pattern: string) => {
   const files = await fs.readdir(await getDir());
-  return files.filter(file => file.includes(pattern));
+  return files.filter((file) => file.includes(pattern));
 };
 
 export const getLinkDetails = async (linkString: string, isSupersede: boolean = false): Promise<LinkDetails> => {

package/src/lib/manipulator.test.ts

@@ -1,49 +1,50 @@
 import { describe, expect, it } from 'vitest';
-import { injectLink, getTitleFrom, getLinksFrom } from './manipulator';
+import { getLinksFrom, getTitleFrom, injectLink } from './manipulator.js';
 
 describe('The ADR manipulator', () => {
+  const original =
+    '# NUMBER. TITLE\n' +
+    '\n' +
+    'Date: DATE\n' +
+    '\n' +
+    '## Status\n' +
+    '\n' +
+    'STATUS\n' +
+    '\n' +
+    '## Context\n' +
+    '\n' +
+    'The issue motivating this decision, and any context that influences or constrains the decision.\n' +
+    '\n' +
+    '## Decision\n' +
+    '\n' +
+    "The change that we're proposing or have agreed to implement.\n" +
+    '\n' +
+    '## Consequences\n' +
+    '\n' +
+    'What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.\n';
 
-  const original = '# NUMBER. TITLE\n'
-    + '\n'
-    + 'Date: DATE\n'
-    + '\n'
-    + '## Status\n'
-    + '\n'
-    + 'STATUS\n'
-    + '\n'
-    + '## Context\n'
-    + '\n'
-    + 'The issue motivating this decision, and any context that influences or constrains the decision.\n'
-    + '\n'
-    + '## Decision\n'
-    + '\n'
-    + 'The change that we\'re proposing or have agreed to implement.\n'
-    + '\n'
-    + '## Consequences\n'
-    + '\n'
-    + 'What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.\n';
-
-  const modified = '# NUMBER. TITLE\n'
-    + '\n'
-    + 'Date: DATE\n'
-    + '\n'
-    + '## Status\n'
-    + '\n'
-    + 'STATUS\n'
-    + '\n'
-    + 'INJECTED STUFF\n'
-    + '\n'
-    + '## Context\n'
-    + '\n'
-    + 'The issue motivating this decision, and any context that influences or constrains the decision.\n'
-    + '\n'
-    + '## Decision\n'
-    + '\n'
-    + 'The change that we\'re proposing or have agreed to implement.\n'
-    + '\n'
-    + '## Consequences\n'
-    + '\n'
-    + 'What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.\n';
+  const modified =
+    '# NUMBER. TITLE\n' +
+    '\n' +
+    'Date: DATE\n' +
+    '\n' +
+    '## Status\n' +
+    '\n' +
+    'STATUS\n' +
+    '\n' +
+    'INJECTED STUFF\n' +
+    '\n' +
+    '## Context\n' +
+    '\n' +
+    'The issue motivating this decision, and any context that influences or constrains the decision.\n' +
+    '\n' +
+    '## Decision\n' +
+    '\n' +
+    "The change that we're proposing or have agreed to implement.\n" +
+    '\n' +
+    '## Consequences\n' +
+    '\n' +
+    'What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.\n';
 
   it('can inject links to the status section', () => {
     const test = injectLink(original, 'INJECTED STUFF');
@@ -70,9 +71,7 @@ describe('The ADR manipulator', () => {
   });
 
   it('can extract links from the status section', () => {
-    const original = '## Status\n'
-      + '\n'
-      + 'Superseded by [3. title here](and-a-link-here.md)\n';
+    const original = '## Status\n' + '\n' + 'Superseded by [3. title here](and-a-link-here.md)\n';
     const extractedLink = getLinksFrom(original);
 
     expect(extractedLink[0]).toEqual({
@@ -82,7 +81,5 @@ describe('The ADR manipulator', () => {
       href: 'and-a-link-here.md',
       raw: 'Superseded by [3. title here](and-a-link-here.md)'
     });
-
   });
-
 });

package/src/lib/manipulator.ts

@@ -1,13 +1,13 @@
 import { marked } from 'marked';
 
 const convertToMd = (tokens: marked.Token[]) => {
-  return tokens.map(token => token.raw).join('');
+  return tokens.map((token) => token.raw).join('');
 };
 
 export const getLinksFrom = (markdown: string) => {
   const tokens = marked.lexer(markdown);
   const linkRegex = new RegExp(/^(.*)\s\[(.*)\]\((.*)\)$/);
-  const links = tokens.filter(token => token.type === 'paragraph' && linkRegex.test(token.text));
+  const links = tokens.filter((token) => token.type === 'paragraph' && linkRegex.test(token.text));
 
   return links.map((link) => {
     const linkToken = link as marked.Tokens.Paragraph;
@@ -27,7 +27,7 @@ export const getLinksFrom = (markdown: string) => {
 
 export const getTitleFrom = (adr: string) => {
   const tokens = marked.lexer(adr);
-  const mainHead = tokens.find(token => token.type === 'heading' && token.depth === 1);
+  const mainHead = tokens.find((token) => token.type === 'heading' && token.depth === 1);
   if (!mainHead) {
     throw new Error('No main heading found');
   }
@@ -36,20 +36,27 @@ export const getTitleFrom = (adr: string) => {
 
 export const supersede = (markdown: string, link: string) => {
   const tokens = marked.lexer(markdown);
-  const statusIndex = tokens.findIndex(token => token.type === 'heading' && token.text.toLowerCase() === 'status');
+  const statusIndex = tokens.findIndex((token) => token.type === 'heading' && token.text.toLowerCase() === 'status');
   if (statusIndex < 0) {
     throw new Error('Could not find status section');
   }
   const statusDepth = (tokens[statusIndex] as marked.Tokens.Heading).depth;
-  const followingHeadingIndex = tokens.findIndex((token, index) => token.type === 'heading' && token.depth === statusDepth && index > statusIndex);
-  const followingParagraphIndex = tokens.findIndex((token, index) => token.type === 'paragraph' && index > statusIndex && index < followingHeadingIndex);
+  const followingHeadingIndex = tokens.findIndex(
+    (token, index) => token.type === 'heading' && token.depth === statusDepth && index > statusIndex
+  );
+  const followingParagraphIndex = tokens.findIndex(
+    (token, index) => token.type === 'paragraph' && index > statusIndex && index < followingHeadingIndex
+  );
 
   if (followingParagraphIndex > followingHeadingIndex || followingParagraphIndex === -1) {
     throw new Error('There is no status paragraph. Please format your adr properly');
   }
 
   tokens[followingParagraphIndex] = {
-    type: 'paragraph', text: link, raw: link, tokens: [
+    type: 'paragraph',
+    text: link,
+    raw: link,
+    tokens: [
       {
         type: 'text',
         raw: link,
@@ -62,18 +69,23 @@ export const supersede = (markdown: string, link: string) => {
 
 export const injectLink = (markdown: string, link: string) => {
   const tokens = marked.lexer(markdown);
-  const statusIndex = tokens.findIndex(token => token.type === 'heading' && token.text.toLowerCase() === 'status');
+  const statusIndex = tokens.findIndex((token) => token.type === 'heading' && token.text.toLowerCase() === 'status');
   if (statusIndex < 0) {
     throw new Error('Could not find status section');
   }
 
   const statusDepth = (tokens[statusIndex] as marked.Tokens.Heading).depth;
-  let followingHeadingIndex = tokens.findIndex((token, index) => token.type === 'heading' && token.depth === statusDepth && index > statusIndex);
+  let followingHeadingIndex = tokens.findIndex(
+    (token, index) => token.type === 'heading' && token.depth === statusDepth && index > statusIndex
+  );
   if (followingHeadingIndex < 0) {
     followingHeadingIndex = tokens.length;
   }
   tokens.splice(followingHeadingIndex, 0, {
-    type: 'paragraph', text: link, raw: link, tokens: [
+    type: 'paragraph',
+    text: link,
+    raw: link,
+    tokens: [
       {
         type: 'text',
         raw: link,

package/src/lib/numbering.test.ts

@@ -1,16 +1,15 @@
-import { afterAll, describe, it, vi, expect } from 'vitest';
 import fs from 'fs/promises';
-import { newNumber } from './numbering';
+import { afterAll, describe, expect, it, vi } from 'vitest';
+import { newNumber } from './numbering.js';
 
-type ReaddirMock = () => Promise<String[]>
+type ReaddirMock = () => Promise<string[]>;
 
 vi.mock('fs/promises');
-vi.mock('./config', () => ({
+vi.mock('./config.js', () => ({
   getDir: vi.fn().mockResolvedValue('/')
 }));
 
 describe('The numbering logic', () => {
-
   afterAll(() => {
     vi.resetAllMocks();
   });
@@ -29,10 +28,7 @@ describe('The numbering logic', () => {
   });
 
   it('processes existing files if there is no lockfile', async () => {
-    const fakeFiles: string[] = [
-      '0001-first-file.md',
-      '0002-first-file.md'
-    ];
+    const fakeFiles: string[] = ['0001-first-file.md', '0002-first-file.md'];
     vi.mocked(fs.readFile).mockRejectedValueOnce('no sequence file');
     vi.mocked(fs.readdir as unknown as ReaddirMock).mockResolvedValueOnce(fakeFiles);
     const num = await newNumber();

package/src/lib/numbering.ts

@@ -1,17 +1,17 @@
-import fs from 'fs/promises';
-import { getDir } from './config';
 import * as path from 'path';
+import fs from 'fs/promises';
+import { getDir } from './config.js';
 
 export const newNumber = async () => {
   try {
     const lockfile = await fs.readFile(path.resolve(await getDir(), '.adr-sequence.lock'));
     return parseInt(lockfile.toString().trim(), 10) + 1;
-  } catch (e) {
+  } catch (_e) {
     // This is for backward compatibility. If someone upgrades from an older tool without a lockfile,
     // we create one.
     const filePattern = /^0*(\d+)-.*$/;
     const files = await fs.readdir(await getDir());
-    const numbers = files.map(f => {
+    const numbers = files.map((f) => {
       const adrFile = f.match(filePattern);
       if (adrFile) {
         return parseInt(adrFile[1], 10);
@@ -22,5 +22,4 @@ export const newNumber = async () => {
     const largestNumber = numbers.reduce((a, b) => Math.max(a, b), 0);
     return largestNumber + 1;
   }
-
 };

package/src/lib/prompt.test.ts

@@ -0,0 +1,42 @@
+import { faker } from '@faker-js/faker';
+import inquirer, { ListQuestion, Question } from 'inquirer';
+import { describe, expect, it, vi } from 'vitest';
+import { askForClarification } from './prompt.js';
+
+vi.mock('inquirer');
+vi.mock('chalk', () => ({
+  default: {
+    blue: (str: string) => {
+      return `BLUE[${str}]`;
+    }
+  }
+}));
+describe('The prompt helper', () => {
+  it('calls inquirer correctly', async () => {
+    const prompt = vi.mocked(inquirer.prompt);
+    prompt.mockResolvedValueOnce({ target: 'does not matter' });
+
+    const randomChoices = [faker.system.filePath(), faker.system.filePath(), faker.system.filePath()];
+    await askForClarification('this is the search string', randomChoices);
+
+    expect(prompt).toHaveBeenCalledOnce();
+    const calledWith = prompt.mock.calls[0][0] as Question[];
+    expect(calledWith[0].type).toEqual('list');
+    expect((calledWith[0] as ListQuestion).choices).toEqual(randomChoices);
+    expect(calledWith[0].message).toMatchInlineSnapshot(
+      '"Which file do you want to link to for BLUE[this is the search string]?"'
+    );
+  });
+
+  it('returns the selected choice', async () => {
+    const prompt = vi.mocked(inquirer.prompt);
+
+    const randomResult = faker.system.filePath();
+
+    prompt.mockResolvedValueOnce({ target: randomResult });
+
+    const result = await askForClarification('this is the search string', ['does not matter']);
+
+    expect(result).toEqual(randomResult);
+  });
+});

package/src/lib/prompt.ts

@@ -0,0 +1,14 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+
+export const askForClarification = async (searchString: string, matches: string[]) => {
+  const selection = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'target',
+      message: `Which file do you want to link to for ${chalk.blue(searchString)}?`,
+      choices: matches
+    }
+  ]);
+  return selection.target;
+};