@meza/adr-tools 2.0.2 → 2.0.4

package/src/lib/manipulator.test.ts

@@ -1,109 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { getLinksFrom, getTitleFrom, injectLink, supersede } 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 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('throws when status section is missing for supersede', () => {
-    const noStatus = '# NUMBER. TITLE\n';
-    const test = () => supersede(noStatus, 'Superseded by [ADR 1](0001-adr.md)');
-    expect(test).toThrowError('Could not find status section');
-  });
-
-  it('throws when status section has no paragraph', () => {
-    const noStatusParagraph = '# NUMBER. TITLE\n\n## Status\n\n## Context\n';
-    const test = () => supersede(noStatusParagraph, 'Superseded by [ADR 1](0001-adr.md)');
-    expect(test).toThrowError('There is no status paragraph. Please format your adr properly');
-  });
-
-  it('replaces status paragraph when superseding', () => {
-    const markdown = '# NUMBER. TITLE\n\n## Status\n\nAccepted\n\n## Context\n';
-    const link = 'Superseded by [ADR 1](0001-adr.md)';
-    const result = supersede(markdown, link);
-    expect(result).toEqual('# NUMBER. TITLE\n\n## Status\n\nSuperseded by [ADR 1](0001-adr.md)\n\n## Context\n');
-  });
-
-  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('throws when main heading is missing', () => {
-    const test = () => getTitleFrom('No heading here');
-    expect(test).toThrowError('No main heading found');
-  });
-
-  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

@@ -1,98 +0,0 @@
-import { marked, type Token, type Tokens } from 'marked';
-
-const convertToMd = (tokens: 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 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 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 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 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

@@ -1,45 +0,0 @@
-import fs from 'fs/promises';
-import { afterAll, describe, expect, it, vi } from 'vitest';
-import { newNumber } from './numbering.js';
-
-type ReaddirMock = () => Promise<string[]>;
-
-vi.mock('fs/promises');
-vi.mock('./config.js', () => ({
-  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);
-  });
-
-  it('ignores non-adr filenames when deriving numbers', async () => {
-    const fakeFiles: string[] = ['notes.txt', '0005-fifth.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(6);
-  });
-});

package/src/lib/numbering.ts

@@ -1,25 +0,0 @@
-import fs from 'fs/promises';
-import * as path from 'path';
-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) {
-    // 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/opening.test.ts

@@ -1,96 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { chooseOpenPlan } from './adr.js';
-
-describe('chooseOpenPlan', () => {
-  afterEach(() => {
-    vi.unstubAllEnvs();
-  });
-  it('returns none when open is false', () => {
-    expect(chooseOpenPlan({ open: false })).toEqual({ type: 'none' });
-  });
-
-  it('treats open-with as enabling open', () => {
-    expect(chooseOpenPlan({ openWith: 'code --wait' })).toEqual({
-      type: 'app',
-      name: 'code',
-      args: ['--wait']
-    });
-  });
-
-  it('parses quoted arguments', () => {
-    expect(chooseOpenPlan({ openWith: 'code "arg with space"' })).toEqual({
-      type: 'app',
-      name: 'code',
-      args: ['arg with space']
-    });
-  });
-
-  it('unescapes quoted arguments', () => {
-    expect(chooseOpenPlan({ openWith: 'code "arg \\"quoted\\""' })).toEqual({
-      type: 'app',
-      name: 'code',
-      args: ['arg "quoted"']
-    });
-  });
-
-  it('parses single-quoted arguments', () => {
-    expect(chooseOpenPlan({ openWith: "code 'arg with space'" })).toEqual({
-      type: 'app',
-      name: 'code',
-      args: ['arg with space']
-    });
-  });
-
-  it('returns none when open-with is not parseable', () => {
-    expect(chooseOpenPlan({ openWith: '"' })).toEqual({ type: 'none' });
-  });
-
-  it('returns none when open-with is whitespace', () => {
-    expect(chooseOpenPlan({ openWith: '   ' })).toEqual({ type: 'none' });
-  });
-
-  it('returns none when open-with is only quoted whitespace', () => {
-    expect(chooseOpenPlan({ openWith: '"   "' })).toEqual({ type: 'none' });
-  });
-
-  it('handles quoted empty command', () => {
-    expect(chooseOpenPlan({ openWith: '""', open: true })).toEqual({ type: 'default' });
-  });
-
-  it('ignores boolean-like editor values', () => {
-    vi.stubEnv('VISUAL', 'true');
-    vi.stubEnv('EDITOR', 'false');
-    expect(chooseOpenPlan({ open: true })).toEqual({ type: 'default' });
-  });
-
-  it('prefers VISUAL over EDITOR when both are set', () => {
-    vi.stubEnv('VISUAL', 'code');
-    vi.stubEnv('EDITOR', 'vim');
-    expect(chooseOpenPlan({ open: true })).toEqual({ type: 'app', name: 'code', args: [] });
-  });
-
-  it('uses EDITOR when it is not npm injected', () => {
-    vi.stubEnv('EDITOR', 'vim');
-    vi.stubEnv('npm_execpath', '');
-    vi.stubEnv('npm_config_editor', '');
-    expect(chooseOpenPlan({ open: true })).toEqual({ type: 'app', name: 'vim', args: [] });
-  });
-
-  it('falls back to default when EDITOR is npm injected', () => {
-    vi.stubEnv('npm_execpath', '/usr/bin/npm');
-    vi.stubEnv('npm_config_editor', 'vi');
-    vi.stubEnv('EDITOR', 'vi');
-    vi.stubEnv('VISUAL', '');
-
-    expect(chooseOpenPlan({ open: true })).toEqual({ type: 'default' });
-  });
-
-  it('uses EDITOR when npm_config_editor is different', () => {
-    vi.stubEnv('npm_execpath', '/usr/bin/npm');
-    vi.stubEnv('npm_config_editor', 'code');
-    vi.stubEnv('EDITOR', 'vim');
-    vi.stubEnv('VISUAL', '');
-
-    expect(chooseOpenPlan({ open: true })).toEqual({ type: 'app', name: 'vim', args: [] });
-  });
-});

package/src/lib/prompt.test.ts

@@ -1,42 +0,0 @@
-import { faker } from '@faker-js/faker';
-import inquirer, { 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('select');
-    expect(calledWith[0].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

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

package/src/lib/template.test.ts

@@ -1,74 +0,0 @@
-import fs from 'fs/promises';
-import path from 'path';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-vi.mock('fs/promises', () => ({
-  default: {
-    readFile: vi.fn()
-  }
-}));
-
-vi.mock('./config.js', () => ({
-  getDir: vi.fn()
-}));
-
-const mockEnv = (key: string, value: string | undefined) => {
-  if (value === undefined) {
-    delete process.env[key];
-    return;
-  }
-  process.env[key] = value;
-};
-
-describe('template', () => {
-  beforeEach(() => {
-    vi.resetModules();
-    vi.mocked(fs.readFile).mockReset();
-    mockEnv('ADR_TEMPLATE', undefined);
-  });
-
-  afterEach(() => {
-    mockEnv('ADR_TEMPLATE', undefined);
-    vi.restoreAllMocks();
-  });
-
-  it('uses the explicit template file when provided', async () => {
-    const { template } = await import('./template.js');
-    vi.mocked(fs.readFile).mockResolvedValueOnce('custom');
-
-    const result = await template('/tmp/custom.md');
-    expect(result).toEqual('custom');
-    expect(fs.readFile).toHaveBeenCalledWith(path.resolve('/tmp/custom.md'), 'utf8');
-  });
-
-  it('uses ADR_TEMPLATE when set', async () => {
-    const { template } = await import('./template.js');
-    mockEnv('ADR_TEMPLATE', '/tmp/env.md');
-    vi.mocked(fs.readFile).mockResolvedValueOnce('env');
-
-    const result = await template();
-    expect(result).toEqual('env');
-    expect(fs.readFile).toHaveBeenCalledWith(path.resolve('/tmp/env.md'), 'utf8');
-  });
-
-  it('uses template from adr directory when available', async () => {
-    const { template } = await import('./template.js');
-    const { getDir } = await import('./config.js');
-    vi.mocked(getDir).mockResolvedValueOnce('/repo/doc/adr');
-    vi.mocked(fs.readFile).mockResolvedValueOnce('repo-template');
-
-    const result = await template();
-    expect(result).toEqual('repo-template');
-    expect(fs.readFile).toHaveBeenCalledWith(path.join('/repo/doc/adr', 'templates/template.md'), 'utf8');
-  });
-
-  it('falls back to built-in template when repo template is missing', async () => {
-    const { template } = await import('./template.js');
-    const { getDir } = await import('./config.js');
-    vi.mocked(getDir).mockResolvedValueOnce('/repo/doc/adr');
-    vi.mocked(fs.readFile).mockRejectedValueOnce(new Error('missing')).mockResolvedValueOnce('built-in');
-
-    const result = await template();
-    expect(result).toEqual('built-in');
-  });
-});

package/src/lib/template.ts

@@ -1,22 +0,0 @@
-import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import fs from 'fs/promises';
-import { getDir } from './config.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-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

@@ -1,21 +0,0 @@
-# 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).

package/src/templates/template.md

@@ -1,19 +0,0 @@
-# NUMBER. TITLE
-
-Date: DATE
-
-## Status
-
-STATUS
-
-## Context
-
-The issue motivating this decision, and any context that influences or constrains the decision.
-
-## Decision
-
-The change that we're proposing or have agreed to implement.
-
-## Consequences
-
-What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.

package/src/types/environment.d.ts

@@ -1,14 +0,0 @@
-declare global {
-  // eslint-disable-next-line no-unused-vars
-  namespace NodeJS {
-    // eslint-disable-next-line no-unused-vars
-    interface ProcessEnv {
-      ADR_TEMPLATE: string;
-      ADR_DATE: string;
-      VISUAL: string;
-      EDITOR: string;
-    }
-  }
-}
-
-export {};

package/src/version.ts

@@ -1 +0,0 @@
-export const LIB_VERSION = '2.0.2';

package/tests/.adr-dir

@@ -1 +0,0 @@
-f8877fa6-908f-4cf5-91cb-9a910b9376f7

package/tests/__snapshots__/generate-graph.e2e.test.ts.snap

@@ -1,39 +0,0 @@
-// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-
-exports[`Generating Graphs > should generate a graph 1`] = `
-"digraph {
-  node [shape=plaintext];
-  subgraph {
-    _1 [label="1. Record architecture decisions"; URL="0001-record-architecture-decisions.html"];
-    _2 [label="2. An idea that seems good at the time"; URL="0002-an-idea-that-seems-good-at-the-time.html"];
-    _1 -> _2 [style="dotted", weight=1];
-    _3 [label="3. A better idea"; URL="0003-a-better-idea.html"];
-    _2 -> _3 [style="dotted", weight=1];
-    _4 [label="4. This will work"; URL="0004-this-will-work.html"];
-    _3 -> _4 [style="dotted", weight=1];
-    _5 [label="5. The end"; URL="0005-the-end.html"];
-    _4 -> _5 [style="dotted", weight=1];
-  }
-  _3 -> _2 [label="Supersedes", weight=0]
-  _5 -> _3 [label="Supersedes", weight=0]
-}"
-`;
-
-exports[`Generating Graphs > should generate a graph with specified route and extension  1`] = `
-"digraph {
-  node [shape=plaintext];
-  subgraph {
-    _1 [label="1. Record architecture decisions"; URL="http://example.com/0001-record-architecture-decisions.xxx"];
-    _2 [label="2. An idea that seems good at the time"; URL="http://example.com/0002-an-idea-that-seems-good-at-the-time.xxx"];
-    _1 -> _2 [style="dotted", weight=1];
-    _3 [label="3. A better idea"; URL="http://example.com/0003-a-better-idea.xxx"];
-    _2 -> _3 [style="dotted", weight=1];
-    _4 [label="4. This will work"; URL="http://example.com/0004-this-will-work.xxx"];
-    _3 -> _4 [style="dotted", weight=1];
-    _5 [label="5. The end"; URL="http://example.com/0005-the-end.xxx"];
-    _4 -> _5 [style="dotted", weight=1];
-  }
-  _3 -> _2 [label="Supersedes", weight=0]
-  _5 -> _3 [label="Supersedes", weight=0]
-}"
-`;