@meza/adr-tools 1.0.1

package/src/lib/adr.ts

@@ -0,0 +1,242 @@
+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';
+
+interface NewOptions {
+  supersedes?: string[];
+  date?: string | undefined;
+  suppressPrompts?: boolean;
+  template?: string;
+  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
+  LINK = 'link',
+  // eslint-disable-next-line no-unused-vars
+  SUPERSEDE = 'supersede'
+}
+
+interface LinkTask {
+  type: LinkType;
+  sourcePath: string;
+  targetPath: string;
+  link: string;
+  reverseLink: string;
+}
+
+const actuallyLink = async (task: LinkTask) => {
+  const linkedFile = path.join(await getDir(), task.targetPath);
+  const newAdrContent = await fs.readFile(task.sourcePath, 'utf8');
+  const oldAdrContent = await fs.readFile(linkedFile, 'utf8');
+  const oldTitle = getTitleFrom(oldAdrContent);
+  const newTitle = getTitleFrom(newAdrContent);
+  let dirtyOld = '', dirtyNew = '';
+  switch (task.type) {
+    case LinkType.LINK:
+      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)})`);
+      dirtyNew = injectLink(newAdrContent, `${task.link} [${oldTitle}](${task.targetPath})`);
+      break;
+    default:
+      break;
+  }
+
+  await fs.writeFile(linkedFile, dirtyOld);
+  await fs.writeFile(task.sourcePath, dirtyNew);
+};
+
+const processSupersedes = async (
+  sourcePath: string,
+  supersedes: string[] = [],
+  suppressPrompts: boolean = false
+) => {
+  if (supersedes.length === 0) {
+    return;
+  }
+
+  const supersedeStrings = await Promise.all(supersedes.map((link) => getLinkDetails(link, true)));
+
+  for (const targetDetails of supersedeStrings) {
+    const task: LinkTask = {
+      type: LinkType.SUPERSEDE,
+      sourcePath: sourcePath,
+      link: targetDetails.link,
+      reverseLink: targetDetails.reverseLink,
+      targetPath: targetDetails.matches[0]
+    };
+
+    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);
+      }
+    }
+
+    await actuallyLink(task);
+  }
+};
+
+const injectLinksTo = async (
+  sourcePath: string,
+  links: string[] = [],
+  suppressPrompts: boolean = false
+) => {
+  if (links.length === 0) {
+    return;
+  }
+
+  const linkStrings = await Promise.all(links.map((link) => getLinkDetails(link)));
+
+  for (const targetDetails of linkStrings) {
+    const task: LinkTask = {
+      type: LinkType.LINK,
+      sourcePath: sourcePath,
+      link: targetDetails.link,
+      reverseLink: targetDetails.reverseLink,
+      targetPath: targetDetails.matches[0]
+    };
+
+    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);
+      }
+    }
+
+    await actuallyLink(task);
+  }
+
+};
+//Generate a table of contents for the adr directory
+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 titles = toc.map(async (file) => {
+    const title = getTitleFrom(await fs.readFile(path.join(adrDir, file), 'utf8'));
+    return `[${title}](${options?.prefix || ''}${file})`;
+  });
+
+  const resolvedTitles = await Promise.all(titles);
+
+  const tocFile = path.resolve(path.join(adrDir, 'decisions.md'));
+  await fs.writeFile(tocFile, `# Table of Contents\n\n${resolvedTitles.join('\n')}`);
+};
+
+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 paddedNumber = newNum.toString().padStart(4, '0');
+  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 generateToc();
+  const newAdrPath = path.relative(workingDir(), adrPath);
+
+  if (process.env.VISUAL) {
+    await childProcess.spawn(process.env.VISUAL, [adrPath], {
+      stdio: 'inherit',
+      shell: true
+    });
+    return;
+  }
+  if (process.env.EDITOR) {
+    await childProcess.spawn(process.env.EDITOR, [adrPath], {
+      stdio: 'inherit',
+      shell: true
+    });
+    return;
+  }
+  console.log(newAdrPath);
+
+};
+
+export const init = async (directory?: string) => {
+  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', {
+    date: process.env.ADR_DATE,
+    template: path.resolve(path.dirname(__filename), '../templates/init.md')
+  });
+};
+
+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) {
+      return found[0];
+    }
+
+    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.');
+    }
+
+    return askForClarification(pattern, found);
+  };
+
+  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 !== '');
+  return toc;
+};

package/src/lib/config.ts

@@ -0,0 +1,34 @@
+import fs from 'fs/promises';
+import { constants } from 'fs';
+import path from 'path';
+
+export const workingDir = () => process.cwd();
+
+const findTopLevelDir = async (dir: string): Promise<string> => {
+  try {
+    await fs.access(path.join(dir, '.adr-dir'), constants.F_OK);
+    return dir;
+  } catch (e) {
+    if (dir === '/') {
+      throw new Error('No ADR directory config found');
+    }
+    const newDir = path.join(dir, '..');
+    return findTopLevelDir(newDir);
+  }
+};
+
+const getDirPath = async (): Promise<string> => {
+  try {
+    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) {
+    return path.resolve(path.join(workingDir(), 'doc/adr'));
+  }
+};
+
+export const getDir = async (): Promise<string> => {
+  const dir = await getDirPath();
+  await fs.mkdir(dir, { recursive: true });
+  return dir;
+};

package/src/lib/links.test.ts

@@ -0,0 +1,86 @@
+import { vi, describe, it, expect, afterEach } from 'vitest';
+import fs from 'fs/promises';
+import { getDir } from './config';
+import { getLinkDetails } from './links';
+
+vi.mock('./config');
+vi.mock('fs/promises');
+
+describe('The link lib', () => {
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it('does not care if there are no matches', async () => {
+    vi.mocked(getDir).mockResolvedValueOnce('/');
+    vi.mocked(fs.readdir).mockResolvedValueOnce([] as any);
+    const linkString = '1:overrides:overriden by';
+    const response = await getLinkDetails(linkString);
+    expect(response).toEqual({
+      pattern: '1',
+      original: '1:overrides:overriden by',
+      link: 'overrides',
+      reverseLink: 'overriden by',
+      matches: []
+    });
+  });
+
+  it('does handles multiple matches', async () => {
+    vi.mocked(getDir).mockResolvedValueOnce('/');
+    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({
+      pattern: '1',
+      original: '1:overrides:overriden by',
+      link: 'overrides',
+      reverseLink: 'overriden by',
+      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);
+    const linkString = '1:overrides:overriden by';
+    const response = await getLinkDetails(linkString);
+    expect(response).toEqual({
+      pattern: '1',
+      original: '1:overrides:overriden by',
+      link: 'overrides',
+      reverseLink: 'overriden by',
+      matches: [
+        'on1e',
+        '1-two'
+      ]
+    });
+  });
+
+  it('handles superseding', async () => {
+    vi.mocked(getDir).mockResolvedValueOnce('/');
+    vi.mocked(fs.readdir).mockResolvedValueOnce([] as any);
+    const linkString = '1';
+    const supersede = true;
+    const response = await getLinkDetails(linkString, supersede);
+    expect(response).toEqual({
+      pattern: '1',
+      original: '1',
+      link: 'Supersedes',
+      reverseLink: 'Superseded by',
+      matches: []
+    });
+  });
+
+});

package/src/lib/links.ts

@@ -0,0 +1,34 @@
+import fs from 'fs/promises';
+import { getDir } from './config';
+
+export interface LinkDetails {
+  pattern: string;
+  original: string;
+  link: string;
+  reverseLink: string;
+  matches: string[];
+}
+
+export const findMatchingFilesFor = async (pattern: string) => {
+  const files = await fs.readdir(await getDir());
+  return files.filter(file => file.includes(pattern));
+};
+
+export const getLinkDetails = async (linkString: string, isSupersede: boolean = false): Promise<LinkDetails> => {
+  const parts = linkString.split(':');
+  const pattern = parts[0];
+  let link = 'Supersedes';
+  let reverseLink = 'Superseded by';
+  if (!isSupersede) {
+    link = parts[1];
+    reverseLink = parts[2];
+  }
+  const files = await findMatchingFilesFor(pattern);
+  return {
+    pattern: pattern,
+    original: linkString,
+    link: link,
+    reverseLink: reverseLink,
+    matches: files
+  };
+};

package/src/lib/manipulator.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import { injectLink, getTitleFrom, getLinksFrom } from './manipulator';
+
+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 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');
+    expect(test).toEqual(modified);
+  });
+
+  it('throws an error when status cannot be found', () => {
+    const noStatus = '# NUMBER. TITLE\n';
+    const test = () => injectLink(noStatus, 'INJECTED STUFF');
+    expect(test).toThrowError('Could not find status section');
+  });
+
+  it('adds to the status section even when there are no following headers', () => {
+    const noFollowingHeaders = '## STATUS\nACCEPTED\n\n';
+    const expected = '## STATUS\nACCEPTED\n\nINJECTED STUFF\n\n';
+    const test = injectLink(noFollowingHeaders, 'INJECTED STUFF');
+    expect(test).toEqual(expected);
+  });
+
+  it('can return the title and number', () => {
+    const original = '# 2. This is the title\n';
+    const test = getTitleFrom(original);
+    expect(test).toEqual('2. This is the title');
+  });
+
+  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 extractedLink = getLinksFrom(original);
+
+    expect(extractedLink[0]).toEqual({
+      label: 'Superseded by',
+      targetNumber: '3',
+      text: '3. title here',
+      href: 'and-a-link-here.md',
+      raw: 'Superseded by [3. title here](and-a-link-here.md)'
+    });
+
+  });
+
+});

package/src/lib/manipulator.ts

@@ -0,0 +1,86 @@
+import { marked } from 'marked';
+
+const convertToMd = (tokens: marked.Token[]) => {
+  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));
+
+  return links.map((link) => {
+    const linkToken = link as marked.Tokens.Paragraph;
+    const linkMatches = linkToken.text.match(linkRegex);
+    if (!linkMatches || linkMatches.length < 3) {
+      throw new Error(`Could not parse link from "${linkToken.text}"`);
+    }
+    return {
+      targetNumber: linkMatches[2].substring(0, linkMatches[2].indexOf('.')),
+      label: linkMatches[1],
+      href: linkMatches[3],
+      text: linkMatches[2],
+      raw: linkMatches[0]
+    };
+  });
+};
+
+export const getTitleFrom = (adr: string) => {
+  const tokens = marked.lexer(adr);
+  const mainHead = tokens.find(token => token.type === 'heading' && token.depth === 1);
+  if (!mainHead) {
+    throw new Error('No main heading found');
+  }
+  return (mainHead as marked.Tokens.Heading).text.trim();
+};
+
+export const supersede = (markdown: string, link: string) => {
+  const tokens = marked.lexer(markdown);
+  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);
+
+  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: 'text',
+        raw: link,
+        text: link
+      }
+    ]
+  };
+  return convertToMd(tokens);
+};
+
+export const injectLink = (markdown: string, link: string) => {
+  const tokens = marked.lexer(markdown);
+  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);
+  if (followingHeadingIndex < 0) {
+    followingHeadingIndex = tokens.length;
+  }
+  tokens.splice(followingHeadingIndex, 0, {
+    type: 'paragraph', text: link, raw: link, tokens: [
+      {
+        type: 'text',
+        raw: link,
+        text: link
+      }
+    ]
+  });
+  tokens.splice(followingHeadingIndex + 1, 0, { type: 'space', raw: '\n\n' });
+  return convertToMd(tokens);
+};

package/src/lib/numbering.test.ts

@@ -0,0 +1,41 @@
+import { afterAll, describe, it, vi, expect } from 'vitest';
+import fs from 'fs/promises';
+import { newNumber } from './numbering';
+
+type ReaddirMock = () => Promise<String[]>
+
+vi.mock('fs/promises');
+vi.mock('./config', () => ({
+  getDir: vi.fn().mockResolvedValue('/')
+}));
+
+describe('The numbering logic', () => {
+
+  afterAll(() => {
+    vi.resetAllMocks();
+  });
+  it('can read from the sequence file', async () => {
+    const random = Math.floor(Math.random() * 100);
+    vi.mocked(fs.readFile).mockResolvedValueOnce(random.toString());
+    const num = await newNumber();
+    expect(num).toEqual(random + 1);
+  });
+
+  it('returns 1 if there are no files', async () => {
+    vi.mocked(fs.readFile).mockRejectedValueOnce('no sequence file');
+    vi.mocked(fs.readdir).mockResolvedValueOnce([]);
+    const num = await newNumber();
+    expect(num).toEqual(1);
+  });
+
+  it('processes existing files if there is no lockfile', async () => {
+    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();
+    expect(num).toEqual(3);
+  });
+});

package/src/lib/numbering.ts

@@ -0,0 +1,26 @@
+import fs from 'fs/promises';
+import { getDir } from './config';
+import * as path from 'path';
+
+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) {
+    // 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 adrFile = f.match(filePattern);
+      if (adrFile) {
+        return parseInt(adrFile[1], 10);
+      }
+      return 0;
+    });
+
+    const largestNumber = numbers.reduce((a, b) => Math.max(a, b), 0);
+    return largestNumber + 1;
+  }
+
+};

package/src/lib/template.ts

@@ -0,0 +1,18 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { getDir } from './config';
+
+export const template = async (templateFile?: string): Promise<string> => {
+  if (templateFile) {
+    return await fs.readFile(path.resolve(templateFile), 'utf8');
+  }
+  if (process.env.ADR_TEMPLATE) {
+    return await fs.readFile(path.resolve(process.env.ADR_TEMPLATE), 'utf8');
+  }
+
+  try {
+    return await fs.readFile(path.join(await getDir(), 'templates/template.md'), 'utf8');
+  } catch (e) {
+    return await fs.readFile(path.resolve(path.join(__dirname, '../templates/template.md')), 'utf8');
+  }
+};

package/src/templates/init.md

@@ -0,0 +1,21 @@
+# 1. Record architecture decisions
+
+Date: DATE
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above.
+For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).
+> For a node version of the same tooling, see Meza's [adr-tools](https://github.com/meza/adr-tools).