@meza/adr-tools 2.0.3 → 2.0.4

package/src/lib/adr.ts

@@ -1,384 +0,0 @@
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import fs from 'fs/promises';
-import type { Options as OpenOptions } from 'open';
-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);
-
-const normalizeEditorCommand = (raw: string | undefined): string | undefined => {
-  if (!raw) {
-    return undefined;
-  }
-
-  const trimmed = raw.trim();
-  if (!trimmed) {
-    return undefined;
-  }
-
-  const unquoted = trimmed.replace(/^['"](.+)['"]$/, '$1').trim();
-  if (!unquoted) {
-    return undefined;
-  }
-
-  const lowered = unquoted.toLowerCase();
-  if (lowered === 'true' || lowered === 'false') {
-    return undefined;
-  }
-
-  return unquoted;
-};
-
-const unescapeDoubleQuoted = (value: string): string => {
-  let result = '';
-  for (let i = 0; i < value.length; i++) {
-    const ch = value[i];
-    if (ch === '\\' && i + 1 < value.length) {
-      const next = value[i + 1];
-      if (next === '\\' || next === '"') {
-        result += next;
-        i++;
-        continue;
-      }
-    }
-    result += ch;
-  }
-  return result;
-};
-
-const splitCommandLine = (commandLine: string): string[] => {
-  const tokens = commandLine.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g);
-  if (!tokens) {
-    return [];
-  }
-
-  return tokens.map((token) => {
-    if (token.startsWith('"') && token.endsWith('"')) {
-      return unescapeDoubleQuoted(token.slice(1, -1));
-    }
-
-    if (token.startsWith("'") && token.endsWith("'")) {
-      return token.slice(1, -1);
-    }
-
-    return token;
-  });
-};
-
-type OpenPlan = { type: 'none' } | { type: 'default' } | { type: 'app'; name: string; args: string[] };
-
-const openAdr = async (adrPath: string, options: OpenOptions, openPromise: Promise<typeof import('open')>) => {
-  const { default: open } = await openPromise;
-  await open(adrPath, options);
-};
-
-const resolveOpenPlan = (config?: NewOptions): OpenPlan => {
-  if (!config || (config.open === undefined && !config.openWith)) {
-    return chooseOpenPlan(undefined);
-  }
-
-  return chooseOpenPlan({
-    ...(config.open !== undefined ? { open: config.open } : {}),
-    ...(config.openWith ? { openWith: config.openWith } : {})
-  });
-};
-
-const shouldLoadOpenLibrary = (openPlan: OpenPlan) => openPlan.type !== 'none';
-
-const openNewAdr = async (openPlan: OpenPlan, adrPath: string, openPromise?: Promise<typeof import('open')>) => {
-  if (openPlan.type === 'none') {
-    return;
-  }
-
-  if (openPlan.type === 'default') {
-    await openAdr(adrPath, { wait: false }, openPromise!);
-    return;
-  }
-
-  await openAdr(
-    adrPath,
-    { app: { name: openPlan.name, arguments: openPlan.args }, wait: process.platform === 'win32' },
-    openPromise!
-  );
-};
-
-const equalsIgnoreCase = (a: string, b: string) => a.toLowerCase() === b.toLowerCase();
-
-const isNpmInjectedEditor = (editor: string) => {
-  const env = process.env as NodeJS.ProcessEnv & {
-    npm_config_editor?: string;
-    npm_execpath?: string;
-  };
-  const npmEditor = normalizeEditorCommand(env.npm_config_editor);
-  if (!npmEditor) {
-    return false;
-  }
-
-  if (!equalsIgnoreCase(editor, npmEditor)) {
-    return false;
-  }
-
-  return Boolean(env.npm_execpath);
-};
-
-const toAppPlan = (commandLine: string | undefined): OpenPlan | undefined => {
-  const normalized = normalizeEditorCommand(commandLine);
-  if (!normalized) {
-    return undefined;
-  }
-
-  const [name, ...args] = splitCommandLine(normalized);
-  if (!name) {
-    return undefined;
-  }
-
-  return { type: 'app', name, args };
-};
-
-export const chooseOpenPlan = (options?: { open?: boolean; openWith?: string }): OpenPlan => {
-  const openWithPlan = toAppPlan(options?.openWith);
-  const shouldOpen = Boolean(options?.open) || Boolean(openWithPlan);
-  if (!shouldOpen) {
-    return { type: 'none' };
-  }
-
-  if (openWithPlan) {
-    return openWithPlan;
-  }
-
-  const visualPlan = toAppPlan(process.env.VISUAL);
-  if (visualPlan) {
-    return visualPlan;
-  }
-
-  const editorCommand = normalizeEditorCommand(process.env.EDITOR);
-  if (editorCommand && !isNpmInjectedEditor(editorCommand)) {
-    const editorPlan = toAppPlan(editorCommand);
-    if (editorPlan) {
-      return editorPlan;
-    }
-  }
-
-  return { type: 'default' };
-};
-
-interface NewOptions {
-  supersedes?: string[];
-  date?: string | undefined;
-  suppressPrompts?: boolean;
-  template?: string;
-  links?: string[];
-  open?: boolean;
-  openWith?: string;
-}
-
-// 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;
-  }
-
-  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.'
-        );
-      }
-      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.'
-        );
-      }
-      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$/)).sort();
-
-  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 openPlan = resolveOpenPlan(config);
-  const openPromise = shouldLoadOpenLibrary(openPlan) ? import('open') : undefined;
-
-  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(/^-+/, '').replace(/-+$/, '');
-  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();
-
-  await openNewAdr(openPlan, adrPath, openPromise);
-};
-
-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 null;
-      }
-      return {
-        number: Number.parseInt(adrFile[1], 10),
-        path: path.resolve(dir, adrFile[0])
-      };
-    })
-    .filter((entry): entry is { number: number; path: string } => Boolean(entry))
-    .sort((a, b) => a.number - b.number)
-    .map((entry) => entry.path);
-  return toc;
-};

package/src/lib/config.test.ts

@@ -1,69 +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: {
-    access: vi.fn(),
-    readFile: vi.fn(),
-    mkdir: vi.fn()
-  }
-}));
-
-const setupModule = async (cwd: string) => {
-  vi.resetModules();
-  vi.spyOn(process, 'cwd').mockReturnValue(cwd);
-  const module = await import('./config.js');
-  return module;
-};
-
-describe('config', () => {
-  beforeEach(() => {
-    vi.mocked(fs.access).mockReset();
-    vi.mocked(fs.readFile).mockReset();
-    vi.mocked(fs.mkdir).mockReset();
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it('uses configured adr directory when .adr-dir exists', async () => {
-    const cwd = path.join(path.parse(process.cwd()).root, 'repo');
-    const { getDir, workingDir } = await setupModule(cwd);
-    vi.mocked(fs.access).mockResolvedValueOnce(undefined);
-    vi.mocked(fs.readFile).mockResolvedValueOnce('doc/adr');
-
-    const dir = await getDir();
-    expect(workingDir()).toEqual(cwd);
-    expect(dir).toEqual(path.join('doc', 'adr'));
-    expect(fs.mkdir).toHaveBeenCalledWith(path.join('doc', 'adr'), { recursive: true });
-  });
-
-  it('falls back to doc/adr when no config exists', async () => {
-    const cwd = path.join(path.parse(process.cwd()).root, 'repo');
-    const { getDir } = await setupModule(cwd);
-    vi.mocked(fs.access).mockRejectedValue(new Error('missing'));
-
-    const dir = await getDir();
-    expect(dir).toEqual(path.resolve(cwd, 'doc/adr'));
-    expect(fs.mkdir).toHaveBeenCalledWith(path.resolve(cwd, 'doc/adr'), { recursive: true });
-  });
-
-  it('resolves .adr-dir from a parent directory', async () => {
-    const repoRoot = path.join(path.parse(process.cwd()).root, 'repo');
-    const cwd = path.join(repoRoot, 'subdir');
-    const { getDir } = await setupModule(cwd);
-    vi.mocked(fs.access).mockImplementation(async (target) => {
-      const targetPath = typeof target === 'string' ? target : target.toString();
-      if (targetPath === path.join(repoRoot, '.adr-dir')) {
-        return;
-      }
-      throw new Error('missing');
-    });
-    vi.mocked(fs.readFile).mockResolvedValueOnce('doc/adr');
-
-    const dir = await getDir();
-    expect(dir).toEqual(path.join('..', 'doc/adr'));
-  });
-});

package/src/lib/config.ts

@@ -1,36 +0,0 @@
-import { constants } from 'fs';
-import fs from 'fs/promises';
-import path from 'path';
-
-export const workingDir = () => process.cwd();
-const rootDir = path.parse(process.cwd()).root;
-
-const findTopLevelDir = async (dir: string): Promise<string> => {
-  try {
-    // CLI paths may point anywhere the invoking user can access; OS permissions are the security boundary.
-    await fs.access(path.join(dir, '.adr-dir'), constants.F_OK); // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
-    return dir;
-  } catch (_e) {
-    if (dir === rootDir) {
-      throw new Error('No ADR directory config found');
-    }
-    const newDir = path.join(dir, '..'); // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
-    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

@@ -1,74 +0,0 @@
-import fs from 'fs/promises';
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { getDir } from './config.js';
-import { getLinkDetails } from './links.js';
-
-vi.mock('./config.js');
-vi.mock('fs/promises');
-
-describe('The link lib', () => {
-  const mockReaddir = vi.mocked(fs.readdir) as unknown as {
-    mockResolvedValueOnce: (value: string[]) => void;
-  };
-
-  afterEach(() => {
-    vi.resetAllMocks();
-  });
-
-  it('does not care if there are no matches', async () => {
-    vi.mocked(getDir).mockResolvedValueOnce('/');
-    mockReaddir.mockResolvedValueOnce([]);
-    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('/');
-    mockReaddir.mockResolvedValueOnce(['1-one', '1-two', '1-three']);
-    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('/');
-    mockReaddir.mockResolvedValueOnce(['on1e', '1-two', 'three']);
-    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('/');
-    mockReaddir.mockResolvedValueOnce([]);
-    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

@@ -1,34 +0,0 @@
-import fs from 'fs/promises';
-import { getDir } from './config.js';
-
-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-errors.test.ts

@@ -1,22 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-
-vi.mock('marked', () => ({
-  marked: {
-    lexer: () => [
-      {
-        type: 'paragraph',
-        text: {
-          toString: () => 'Superseded by [1. title](0001-title.md)',
-          match: () => null
-        }
-      }
-    ]
-  }
-}));
-
-describe('The ADR manipulator error cases', () => {
-  it('throws when a link cannot be parsed', async () => {
-    const { getLinksFrom } = await import('./manipulator.js');
-    expect(() => getLinksFrom('ignored')).toThrowError('Could not parse link from');
-  });
-});