@meza/adr-tools 1.0.12 → 2.0.0

package/src/index.test.ts

@@ -0,0 +1,212 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import chalk from 'chalk';
+import type { Command } from 'commander';
+import { describe, expect, it, vi } from 'vitest';
+import { buildProgram, defaultOnError, isDirectRun, maybeRun, run } from './index.js';
+
+const createDeps = () => {
+  const deps = {
+    generateToc: vi.fn(),
+    init: vi.fn(),
+    link: vi.fn(),
+    listAdrs: vi.fn(),
+    newAdr: vi.fn(),
+    workingDir: vi.fn(),
+    readFile: vi.fn(),
+    getLinksFrom: vi.fn(),
+    getTitleFrom: vi.fn(),
+    version: '1.2.3',
+    onError: vi.fn(),
+    log: vi.fn(),
+    warn: vi.fn()
+  };
+
+  return deps;
+};
+
+describe('adr CLI', () => {
+  it('wires program metadata', () => {
+    const deps = createDeps();
+    const program = buildProgram(deps);
+    expect(program.name()).toEqual('adr');
+    expect(program.version()).toEqual('1.2.3');
+  });
+
+  it('runs the new command with options', async () => {
+    const deps = createDeps();
+    await run(['node', 'adr', 'new', 'My', 'ADR', '--open'], deps);
+    expect(deps.newAdr).toHaveBeenCalledWith('My ADR', {
+      supersedes: [],
+      date: process.env.ADR_DATE,
+      suppressPrompts: false,
+      links: [],
+      open: true,
+      openWith: undefined
+    });
+  });
+
+  it('invokes error handler when newAdr fails', async () => {
+    const deps = createDeps();
+    deps.newAdr.mockRejectedValueOnce(new Error('boom'));
+    await run(['node', 'adr', 'new', 'My', 'ADR'], deps);
+    expect(deps.onError).toHaveBeenCalled();
+  });
+
+  it('routes generate toc', async () => {
+    const deps = createDeps();
+    await run(['node', 'adr', 'generate', 'toc', '-p', '/prefix/'], deps);
+    expect(deps.generateToc).toHaveBeenCalledWith({ prefix: '/prefix/' });
+  });
+
+  it('generates graph output', async () => {
+    const deps = createDeps();
+    deps.listAdrs.mockResolvedValue(['/repo/doc/adr/0001-one.md', '/repo/doc/adr/0002-two.md']);
+    deps.readFile.mockResolvedValue('# Title');
+    deps.getTitleFrom.mockReturnValue('ADR Title');
+    deps.getLinksFrom.mockReturnValue([
+      { label: 'Relates to', targetNumber: '0002' },
+      { label: 'Superseded by', targetNumber: '0003' }
+    ]);
+    await run(['node', 'adr', 'generate', 'graph', '-e', '.md', '-p', '/p/'], deps);
+    const output = deps.log.mock.calls[0][0] as string;
+    expect(output).toContain('digraph');
+    expect(output).toContain('_1 -> _2 [style="dotted"');
+    expect(output).toContain('label="Relates to"');
+    expect(output).not.toContain('Superseded by');
+  });
+
+  it('generates graph output with default prefix', async () => {
+    const deps = createDeps();
+    deps.listAdrs.mockResolvedValue(['/repo/doc/adr/0001-one.md']);
+    deps.readFile.mockResolvedValue('# Title');
+    deps.getTitleFrom.mockReturnValue('ADR Title');
+    deps.getLinksFrom.mockReturnValue([]);
+    await run(['node', 'adr', 'generate', 'graph'], deps);
+    const output = deps.log.mock.calls[0][0] as string;
+    expect(output).toContain('0001-one.html');
+  });
+
+  it('links graph nodes by adr number', async () => {
+    const deps = createDeps();
+    deps.listAdrs.mockResolvedValue(['/repo/doc/adr/0001-one.md', '/repo/doc/adr/0003-three.md']);
+    deps.readFile.mockResolvedValue('# Title');
+    deps.getTitleFrom.mockReturnValue('ADR Title');
+    deps.getLinksFrom.mockReturnValue([{ label: 'Relates to', targetNumber: '3' }]);
+    await run(['node', 'adr', 'generate', 'graph'], deps);
+    const output = deps.log.mock.calls[0][0] as string;
+    expect(output).toContain('_1 -> _3 [style="dotted"');
+    expect(output).toContain('_1 -> _3 [label="Relates to"');
+  });
+
+  it('skips graph links that target missing nodes', async () => {
+    const deps = createDeps();
+    deps.listAdrs.mockResolvedValue(['/repo/doc/adr/0001-one.md']);
+    deps.readFile.mockResolvedValue('# Title');
+    deps.getTitleFrom.mockReturnValue('ADR Title');
+    deps.getLinksFrom.mockReturnValue([{ label: 'Relates to', targetNumber: '99' }]);
+    await run(['node', 'adr', 'generate', 'graph'], deps);
+    const output = deps.log.mock.calls[0][0] as string;
+    expect(output).not.toContain('_1 -> _99');
+    expect(deps.warn).toHaveBeenCalledWith('Skipping graph link from ADR 1 to missing ADR 99: Relates to');
+  });
+
+  it('skips files without numeric prefixes', async () => {
+    const deps = createDeps();
+    deps.listAdrs.mockResolvedValue(['/repo/doc/adr/notes.md', '/repo/doc/adr/0001-one.md']);
+    deps.readFile.mockResolvedValue('# Title');
+    deps.getTitleFrom.mockReturnValue('ADR Title');
+    deps.getLinksFrom.mockReturnValue([]);
+    await run(['node', 'adr', 'generate', 'graph'], deps);
+    expect(deps.readFile).toHaveBeenCalledTimes(2);
+    expect(deps.readFile).toHaveBeenNthCalledWith(1, '/repo/doc/adr/0001-one.md', 'utf8');
+    expect(deps.readFile).toHaveBeenNthCalledWith(2, '/repo/doc/adr/0001-one.md', 'utf8');
+  });
+
+  it('escapes graph labels and urls', async () => {
+    const deps = createDeps();
+    deps.listAdrs.mockResolvedValue(['/repo/doc/adr/0001-one.md']);
+    deps.readFile.mockResolvedValue('# Title');
+    deps.getTitleFrom.mockReturnValue('ADR "Title" \\\\ path\nline');
+    deps.getLinksFrom.mockReturnValue([]);
+    await run(['node', 'adr', 'generate', 'graph', '-e', '.md', '-p', '/p/"weird"/'], deps);
+    const output = deps.log.mock.calls[0][0] as string;
+    const match = output.match(/label="([\s\S]*?)"; URL="([^"]+)"/);
+    expect(match?.[1]).toContain(String.raw`ADR \"Title\" \\\\ path\\nline`);
+    expect(match?.[1]).not.toContain('\n');
+    expect(output).toContain(String.raw`URL="/p/\"weird\"/0001-one.md"`);
+  });
+
+  it('routes link command', async () => {
+    const deps = createDeps();
+    await run(['node', 'adr', 'link', '1', 'Amends', '2', 'Amended by'], deps);
+    const call = deps.link.mock.calls[0];
+    expect(call.slice(0, 4)).toEqual(['1', 'Amends', '2', 'Amended by']);
+  });
+
+  it('routes init command', async () => {
+    const deps = createDeps();
+    await run(['node', 'adr', 'init', 'doc/adr'], deps);
+    expect(deps.init).toHaveBeenCalledWith('doc/adr');
+  });
+
+  it('lists adrs relative to working dir', async () => {
+    const deps = createDeps();
+    deps.listAdrs.mockResolvedValue(['/repo/doc/adr/0001-one.md']);
+    deps.workingDir.mockReturnValue('/repo');
+    await run(['node', 'adr', 'list'], deps);
+    expect(deps.log).toHaveBeenCalledWith(path.join('doc', 'adr', '0001-one.md'));
+  });
+
+  it('collects repeated options for links and supersedes', async () => {
+    const deps = createDeps();
+    await run(
+      [
+        'node',
+        'adr',
+        'new',
+        'My',
+        'ADR',
+        '-l',
+        '1:Links:Linked by',
+        '-l',
+        '2:Relates:Related by',
+        '-s',
+        '1',
+        '-s',
+        '2'
+      ],
+      deps
+    );
+    const [, options] = deps.newAdr.mock.calls[0];
+    expect(options.links).toEqual(['1:Links:Linked by', '2:Relates:Related by']);
+    expect(options.supersedes).toEqual(['1', '2']);
+  });
+
+  it('detects direct runs based on argv', () => {
+    const indexPath = path.resolve(process.cwd(), 'src/index.ts');
+    const moduleUrl = pathToFileURL(indexPath).href;
+    expect(isDirectRun(['node', indexPath], moduleUrl)).toBe(true);
+    expect(isDirectRun(['node'], moduleUrl)).toBe(false);
+  });
+
+  it('returns false when maybeRun is not direct', () => {
+    const deps = createDeps();
+    expect(maybeRun(['node', '/other/entry'], deps)).toBe(false);
+  });
+
+  it('runs when maybeRun detects direct execution', async () => {
+    const deps = createDeps();
+    deps.listAdrs.mockResolvedValue([]);
+    const indexPath = path.resolve(process.cwd(), 'src/index.ts');
+    expect(maybeRun(['node', indexPath, 'list'], deps)).toBe(true);
+    expect(deps.listAdrs).toHaveBeenCalled();
+  });
+
+  it('formats errors with the default handler', () => {
+    const errorHandler = vi.fn();
+    const program = { error: errorHandler } as unknown as Command;
+    defaultOnError(program, new Error('boom'));
+    expect(errorHandler).toHaveBeenCalledWith(chalk.red('boom'), { exitCode: 1 });
+  });
+});

package/src/index.ts

@@ -1,16 +1,15 @@
 #!/usr/bin/env node
 
-import * as path from 'path';
+import fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import { Command } from 'commander';
-import fs from 'fs/promises';
 import { generateToc, init, link, listAdrs, newAdr } from './lib/adr.js';
 import { workingDir } from './lib/config.js';
 import { getLinksFrom, getTitleFrom } from './lib/manipulator.js';
 import { LIB_VERSION } from './version.js';
 
-const program = new Command();
-
 const collectLinks = (val: string, memo: string[]) => {
   memo.push(val);
   return memo;
@@ -21,120 +20,242 @@ const collectSupersedes = (val: string, memo: string[]) => {
   return memo;
 };
 
-const generateGraph = async (options?: { prefix: string; extension: string }) => {
-  let text = 'digraph {\n';
-  text += '  node [shape=plaintext];\n';
-  text += '  subgraph {\n';
-
-  const adrs = await listAdrs();
-  for (let i = 0; i < adrs.length; i++) {
-    const n = i + 1;
-    const adrPath = adrs[i];
-    const contents = await fs.readFile(adrPath, 'utf8');
-    const title = getTitleFrom(contents);
-    text += `    _${n} [label="${title}"; URL="${options?.prefix || ''}${path.basename(adrPath, '.md')}${options?.extension}"];\n`;
-    if (n > 1) {
-      text += `    _${n - 1} -> _${n} [style="dotted", weight=1];\n`;
+type ProgramDeps = {
+  generateToc: typeof generateToc;
+  init: typeof init;
+  link: typeof link;
+  listAdrs: typeof listAdrs;
+  newAdr: typeof newAdr;
+  workingDir: typeof workingDir;
+  readFile: typeof fs.readFile;
+  getLinksFrom: typeof getLinksFrom;
+  getTitleFrom: typeof getTitleFrom;
+  version: string;
+  onError: (program: Command, error: Error) => void;
+  log: (message: string) => void;
+  warn: (message: string) => void;
+};
+
+export const defaultOnError = (program: Command, error: Error) => {
+  program.error(chalk.red(error.message), { exitCode: 1 });
+};
+
+const defaultDeps: ProgramDeps = {
+  generateToc,
+  init,
+  link,
+  listAdrs,
+  newAdr,
+  workingDir,
+  readFile: fs.readFile,
+  getLinksFrom,
+  getTitleFrom,
+  version: LIB_VERSION,
+  onError: defaultOnError,
+  log: console.log,
+  warn: console.warn
+};
+
+const escapeDotString = (value: string) =>
+  value
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\r\n|\n|\r/g, '\\\\n');
+
+const getAdrNumberFromPath = (adrPath: string): number | undefined => {
+  const baseName = path.basename(adrPath, '.md');
+  const match = baseName.match(/^0*(\d+)-/);
+  if (!match) {
+    return undefined;
+  }
+  return Number.parseInt(match[1], 10);
+};
+
+type GraphNode = { adrPath: string; number: number };
+
+const resolveGraphNodes = (adrs: string[]): GraphNode[] =>
+  adrs
+    .map((adrPath) => ({ adrPath, number: getAdrNumberFromPath(adrPath) }))
+    .filter((node): node is GraphNode => node.number !== undefined);
+
+const appendGraphNodes = async (
+  deps: ProgramDeps,
+  nodes: GraphNode[],
+  options: { prefix?: string; extension?: string } | undefined,
+  lines: string[]
+) => {
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i].number;
+    const adrPath = nodes[i].adrPath;
+    const contents = await deps.readFile(adrPath, 'utf8');
+    const title = deps.getTitleFrom(contents);
+    const url = `${options?.prefix || ''}${path.basename(adrPath, '.md')}${options?.extension}`;
+    lines.push(`    _${n} [label="${escapeDotString(title)}"; URL="${escapeDotString(url)}"];`);
+    const previous = nodes[i - 1]?.number;
+    if (previous !== undefined) {
+      lines.push(`    _${previous} -> _${n} [style="dotted", weight=1];`);
     }
   }
-  text += '  }\n';
-  for (let i = 0; i < adrs.length; i++) {
-    const n = i + 1;
-    const adrPath = adrs[i];
-    const contents = await fs.readFile(adrPath, 'utf8');
-    const linksInADR = getLinksFrom(contents);
-
-    for (let j = 0; j < linksInADR.length; j++) {
-      if (!linksInADR[j].label.endsWith('by')) {
-        text += `  _${n} -> _${linksInADR[j].targetNumber} [label="${linksInADR[j].label}", weight=0]\n`;
+};
+
+const resolveTargetNodeId = (nodeIds: Set<number>, targetNumber: string): number | undefined => {
+  const number = Number.parseInt(targetNumber, 10);
+  if (!Number.isFinite(number) || !nodeIds.has(number)) {
+    return undefined;
+  }
+  return number;
+};
+
+const appendGraphEdges = async (deps: ProgramDeps, nodes: GraphNode[], lines: string[]) => {
+  const nodeIds = new Set(nodes.map((node) => node.number));
+  for (const node of nodes) {
+    const contents = await deps.readFile(node.adrPath, 'utf8');
+    const linksInADR = deps.getLinksFrom(contents);
+    for (const link of linksInADR) {
+      if (link.label.endsWith('by')) {
+        continue;
+      }
+      const target = resolveTargetNodeId(nodeIds, link.targetNumber);
+      if (target !== undefined) {
+        lines.push(`  _${node.number} -> _${target} [label="${link.label}", weight=0]`);
+      } else {
+        deps.warn(`Skipping graph link from ADR ${node.number} to missing ADR ${link.targetNumber}: ${link.label}`);
       }
     }
   }
+};
+
+const generateGraph = async (deps: ProgramDeps, options?: { prefix: string; extension: string }) => {
+  const lines: string[] = [];
+  lines.push('digraph {');
+  lines.push('  node [shape=plaintext];');
+  lines.push('  subgraph {');
 
-  text += '}\n';
-  console.log(text);
+  const adrs = await deps.listAdrs();
+  const nodes = resolveGraphNodes(adrs);
+  await appendGraphNodes(deps, nodes, options, lines);
+
+  lines.push('  }');
+  await appendGraphEdges(deps, nodes, lines);
+  lines.push('}');
+
+  deps.log(`${lines.join('\n')}\n`);
 };
 
-program.name('adr').version(LIB_VERSION).description('Manage Architecture Decision Logs');
-
-program
-  .command('new')
-  .argument('<title...>', 'The title of the decision')
-  .option(
-    '-q, --quiet',
-    'Do not ask for clarification. If multiple files match the search pattern, an error will be thrown.'
-  )
-  .option(
-    '-s, --supersede <SUPERSEDE>',
-    'A reference (number or partial filename) of a previous decision that the new decision supercedes.\n' +
-      'A Markdown link to the superceded ADR is inserted into the Status section.\n' +
-      'The status of the superceded ADR is changed to record that it has been superceded by the new ADR.',
-    collectSupersedes,
-    []
-  )
-  .option(
-    '-l, --link "<TARGET:LINK:REVERSE-LINK>"',
-    'Links the new ADR to a previous ADR.\n' +
-      `${chalk.bold('TARGET')} is a reference (number or partial filename) of a previous decision.\n` +
-      `${chalk.bold('LINK')} is the description of the link created in the new ADR.\n` +
-      `${chalk.bold('REVERSE-LINK')} is the description of the link created in the existing ADR that will refer to the new ADR`,
-    collectLinks,
-    []
-  )
-  .action(async (title: string[], options) => {
-    try {
-      await newAdr(title.join(' '), {
-        supersedes: options.supersede,
-        date: process.env.ADR_DATE,
-        suppressPrompts: options.quiet || false,
-        links: options.link
-      });
-    } catch (e) {
-      program.error(chalk.red((e as Error).message), { exitCode: 1 });
-    }
-  });
+export const buildProgram = (deps: ProgramDeps = defaultDeps) => {
+  const program = new Command();
+  program.name('adr').version(deps.version).description('Manage Architecture Decision Logs');
 
-const generate = program.command('generate');
-
-generate
-  .command('toc')
-  .option('-p, --prefix <PREFIX>', 'The prefix to use for each file link in the generated TOC.')
-  .action((options) => generateToc(options));
-
-generate
-  .command('graph')
-  .option('-p, --prefix <PREFIX>', 'Prefix each decision file link with PREFIX.')
-  .option(
-    '-e, --extension <EXTENSION>',
-    'the file extension of the documents to which generated links refer. Defaults to .html',
-    '.html'
-  )
-  .action(async (options) => {
-    await generateGraph(options);
-  });
+  program
+    .command('new')
+    .argument('<title...>', 'The title of the decision')
+    .option(
+      '-q, --quiet',
+      'Do not ask for clarification. If multiple files match the search pattern, an error will be thrown.'
+    )
+    .option('--open', 'Open the created ADR after writing it (use OS default or `--open-with`).')
+    .option(
+      '--open-with <COMMAND>',
+      'Open the created ADR with a specific command (optionally with args); implies `--open`.'
+    )
+    .option(
+      '-s, --supersede <SUPERSEDE>',
+      'A reference (number or partial filename) of a previous decision that the new decision supercedes.\n' +
+        'A Markdown link to the superceded ADR is inserted into the Status section.\n' +
+        'The status of the superceded ADR is changed to record that it has been superceded by the new ADR.',
+      collectSupersedes,
+      []
+    )
+    .option(
+      '-l, --link "<TARGET:LINK:REVERSE-LINK>"',
+      'Links the new ADR to a previous ADR.\n' +
+        `${chalk.bold('TARGET')} is a reference (number or partial filename) of a previous decision.\n` +
+        `${chalk.bold('LINK')} is the description of the link created in the new ADR.\n` +
+        `${chalk.bold('REVERSE-LINK')} is the description of the link created in the existing ADR that will refer to the new ADR`,
+      collectLinks,
+      []
+    )
+    .action(async (title: string[], options) => {
+      try {
+        await deps.newAdr(title.join(' '), {
+          supersedes: options.supersede,
+          date: process.env.ADR_DATE,
+          suppressPrompts: options.quiet || false,
+          links: options.link,
+          open: options.open || Boolean(options.openWith),
+          openWith: options.openWith
+        });
+      } catch (e) {
+        deps.onError(program, e as Error);
+      }
+    });
+
+  const generate = program.command('generate');
+
+  generate
+    .command('toc')
+    .option('-p, --prefix <PREFIX>', 'The prefix to use for each file link in the generated TOC.')
+    .action((options) => deps.generateToc(options));
+
+  generate
+    .command('graph')
+    .option('-p, --prefix <PREFIX>', 'Prefix each decision file link with PREFIX.')
+    .option(
+      '-e, --extension <EXTENSION>',
+      'the file extension of the documents to which generated links refer. Defaults to .html',
+      '.html'
+    )
+    .action(async (options) => {
+      await generateGraph(deps, options);
+    });
+
+  program
+    .command('link')
+    .argument('<SOURCE>', 'Full or Partial reference number to an ADR')
+    .argument('<LINK>', 'The description of the link created in the SOURCE')
+    .argument('<TARGET>', 'Full or Partial reference number to an ADR')
+    .argument('<REVERSE-LINK>', 'The description of the link created in the TARGET')
+    .option(
+      '-q, --quiet',
+      'Do not ask for clarification. If multiple files match the search pattern, an error will be thrown.'
+    )
+    .action(deps.link);
 
-program
-  .command('link')
-  .argument('<SOURCE>', 'Full or Partial reference number to an ADR')
-  .argument('<LINK>', 'The description of the link created in the SOURCE')
-  .argument('<TARGET>', 'Full or Partial reference number to an ADR')
-  .argument('<REVERSE-LINK>', 'The description of the link created in the TARGET')
-  .option(
-    '-q, --quiet',
-    'Do not ask for clarification. If multiple files match the search pattern, an error will be thrown.'
-  )
-  .action(link);
-
-program
-  .command('init')
-  .argument('[directory]', 'Initialize a new ADR directory')
-  .action(async (directory?: string) => {
-    await init(directory);
+  program
+    .command('init')
+    .argument('[directory]', 'Initialize a new ADR directory')
+    .action(async (directory?: string) => {
+      await deps.init(directory);
+    });
+
+  program.command('list').action(async () => {
+    const adrs = await deps.listAdrs();
+    deps.log(adrs.map((adr) => path.relative(deps.workingDir(), adr)).join('\n'));
   });
 
-program.command('list').action(async () => {
-  const adrs = await listAdrs();
-  console.log(adrs.map((adr) => path.relative(workingDir(), adr)).join('\n'));
-});
+  return program;
+};
+
+export const run = async (argv = process.argv, deps: ProgramDeps = defaultDeps) => {
+  const program = buildProgram(deps);
+  await program.parseAsync(argv);
+  return program;
+};
+
+export const isDirectRun = (argv = process.argv, moduleUrl = import.meta.url) => {
+  if (!argv[1]) {
+    return false;
+  }
+  return path.resolve(argv[1]) === fileURLToPath(moduleUrl);
+};
+
+export const maybeRun = (argv = process.argv, deps?: ProgramDeps) => {
+  if (!isDirectRun(argv)) {
+    return false;
+  }
+  const runPromise = run(argv, deps);
+  runPromise.catch(() => undefined);
+  return true;
+};
 
-program.parse();
+maybeRun();

package/src/inject-version.test.ts

@@ -0,0 +1,31 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+// @ts-expect-error no module types for script import
+import { buildVersionSource, resolveTargetPath, writeVersionFile } from '../scripts/inject-version.mjs';
+
+describe('inject-version script helpers', () => {
+  it('builds the version export', () => {
+    expect(buildVersionSource('1.2.3')).toBe("export const LIB_VERSION = '1.2.3';\n");
+  });
+
+  it('requires an output path', () => {
+    expect(() => resolveTargetPath(['node', 'scripts/inject-version.mjs'])).toThrow(
+      'Usage: node scripts/inject-version.mjs <output-file>'
+    );
+  });
+
+  it('writes the version file', () => {
+    const tmpDir = mkdtempSync(path.join(os.tmpdir(), 'adr-version-'));
+    const targetPath = path.join(tmpDir, 'version.ts');
+
+    try {
+      writeVersionFile(targetPath, '9.9.9');
+      const contents = readFileSync(targetPath, 'utf8');
+      expect(contents).toBe("export const LIB_VERSION = '9.9.9';\n");
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});