@meza/adr-tools 1.0.1

package/src/templates/template.md

@@ -0,0 +1,19 @@
+# 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/version.ts

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

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

@@ -0,0 +1,39 @@
+// Vitest Snapshot v1
+
+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]
+}"
+`;

package/tests/__snapshots__/init-adr-repository.e2e.test.ts.snap

@@ -0,0 +1,51 @@
+// Vitest Snapshot v1
+
+exports[`Init an ADR Repository > should use an alternate directory 1`] = `
+"# 1. Record architecture decisions
+
+Date: 1992-01-12
+
+## 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).
+"
+`;
+
+exports[`Init an ADR Repository > should use the default directory 1`] = `
+"# 1. Record architecture decisions
+
+Date: 1992-01-12
+
+## 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/tests/__snapshots__/linking-records.e2e.test.ts.snap

@@ -0,0 +1,155 @@
+// Vitest Snapshot v1
+
+exports[`Linking Adrs > should link adrs as expected with adr link 1`] = `
+"# 1. First Record
+
+Date: 1992-01-12
+
+## Status
+
+Accepted
+
+Amended by [3. Third Record](0003-third-record.md)
+
+## 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.
+"
+`;
+
+exports[`Linking Adrs > should link adrs as expected with adr link 2`] = `
+"# 2. Second Record
+
+Date: 1992-01-12
+
+## Status
+
+Accepted
+
+Clarified by [3. Third Record](0003-third-record.md)
+
+## 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.
+"
+`;
+
+exports[`Linking Adrs > should link adrs as expected with adr link 3`] = `
+"# 3. Third Record
+
+Date: 1992-01-12
+
+## Status
+
+Accepted
+
+Amends [1. First Record](0001-first-record.md)
+
+Clarifies [2. Second Record](0002-second-record.md)
+
+## 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.
+"
+`;
+
+exports[`Linking Adrs > should link adrs as expected with adr new 1`] = `
+"# 1. First Record
+
+Date: 1992-01-12
+
+## Status
+
+Accepted
+
+Amended by [3. Third Record](0003-third-record.md)
+
+## 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.
+"
+`;
+
+exports[`Linking Adrs > should link adrs as expected with adr new 2`] = `
+"# 2. Second Record
+
+Date: 1992-01-12
+
+## Status
+
+Accepted
+
+Clarified by [3. Third Record](0003-third-record.md)
+
+## 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.
+"
+`;
+
+exports[`Linking Adrs > should link adrs as expected with adr new 3`] = `
+"# 3. Third Record
+
+Date: 1992-01-12
+
+## Status
+
+Accepted
+
+Amends [1. First Record](0001-first-record.md)
+
+Clarifies [2. Second Record](0002-second-record.md)
+
+## 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/tests/__snapshots__/new-adr.e2e.test.ts.snap

@@ -0,0 +1,54 @@
+// Vitest Snapshot v1
+
+exports[`New Adrs > should create a new one even if no config exists 1`] = `
+"# 1. Example ADR
+
+Date: 1992-01-12
+
+## Status
+
+Accepted
+
+## 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.
+"
+`;
+
+exports[`New Adrs > should create a new one normally 1`] = `
+"# 2. Example ADR
+
+Date: 1992-01-12
+
+## Status
+
+Accepted
+
+## 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.
+"
+`;
+
+exports[`New Adrs > should create a table of contents upon creation 1`] = `
+"# Table of Contents
+
+[1. Record architecture decisions](0001-record-architecture-decisions.md)
+[2. Example ADR](0002-example-adr.md)"
+`;

package/tests/__snapshots__/superseding-records.e2e.test.ts.snap

@@ -0,0 +1,122 @@
+// Vitest Snapshot v1
+
+exports[`Superseding Adrs > should be able to supersede multiple records 1`] = `
+"# 1. First Record
+
+Date: 1992-01-12
+
+## Status
+
+Superseded by [3. Third Record](0003-third-record.md)
+
+## 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.
+"
+`;
+
+exports[`Superseding Adrs > should be able to supersede multiple records 2`] = `
+"# 2. Second Record
+
+Date: 1992-01-12
+
+## Status
+
+Superseded by [3. Third Record](0003-third-record.md)
+
+## 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.
+"
+`;
+
+exports[`Superseding Adrs > should be able to supersede multiple records 3`] = `
+"# 3. Third Record
+
+Date: 1992-01-12
+
+## Status
+
+Accepted
+
+Supersedes [1. First Record](0001-first-record.md)
+
+Supersedes [2. Second Record](0002-second-record.md)
+
+## 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.
+"
+`;
+
+exports[`Superseding Adrs > should be able to supersede previous adrs 1`] = `
+"# 1. First Record
+
+Date: 1992-01-12
+
+## Status
+
+Superseded by [2. Second Record](0002-second-record.md)
+
+## 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.
+"
+`;
+
+exports[`Superseding Adrs > should be able to supersede previous adrs 2`] = `
+"# 2. Second Record
+
+Date: 1992-01-12
+
+## Status
+
+Accepted
+
+Supersedes [1. First Record](0001-first-record.md)
+
+## 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/tests/__snapshots__/toc-prefixing.e2e.test.ts.snap

@@ -0,0 +1,9 @@
+// Vitest Snapshot v1
+
+exports[`Generating TOC > should add a path prefix to the toc when there is one supplied 1`] = `
+"# Table of Contents
+
+[1. First Record](foo/doc/adr/0001-first-record.md)
+[2. Second Record](foo/doc/adr/0002-second-record.md)
+[3. Third Record](foo/doc/adr/0003-third-record.md)"
+`;

package/tests/__snapshots__/use-template-override.e2e.test.ts.snap

@@ -0,0 +1,17 @@
+// Vitest Snapshot v1
+
+exports[`Overriding templates > should use an override template if one exists 1`] = `
+"# This is an override template
+Example ADR
+1992-01-12
+2
+Accepted"
+`;
+
+exports[`Overriding templates > should use an override template if one exists 2`] = `
+"# This is an override template
+Another Example ADR
+1992-01-12
+3
+Accepted"
+`;

package/tests/edit-on-create.e2e.test.ts

@@ -0,0 +1,54 @@
+/* eslint-disable no-sync */
+import { describe, it, expect, afterEach, beforeEach } from 'vitest';
+import * as childProcess from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as os from 'os';
+
+describe('Edit new Adrs on creation', () => {
+  const adr = path.resolve(path.dirname(__filename), '../src/index.ts');
+  const command = `npx ts-node ${adr}`;
+  const visualHelper = path.resolve(path.dirname(__filename), './fake-visual');
+  const editorHelper = path.resolve(path.dirname(__filename), './fake-editor');
+
+  let adrDirectory: string;
+  let workDir: string;
+
+  beforeEach(() => {
+    // @ts-ignore
+    process.env.ADR_DATE = '1992-01-12';
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'adr-'));
+    adrDirectory = path.join(workDir, 'doc/adr');
+  });
+
+  afterEach(() => {
+    childProcess.execSync(`rm -rf ${workDir}`);
+  });
+
+  it('should open a new ADR in the VISUAL', () => {
+    childProcess.execSync(`VISUAL="${visualHelper}" ${command} new Example ADR`, { cwd: workDir });
+
+    const expectedNewFile: string = path.join(workDir, 'visual.out');
+    const fileContents = fs.readFileSync(expectedNewFile, 'utf8');
+    expect(fileContents.trim()).toEqual(`VISUAL ${adrDirectory}/0001-example-adr.md`);
+  });
+
+  it('should open a new ADR in the EDITOR', () => {
+    childProcess.execSync(`EDITOR="${editorHelper}" ${command} new Example ADR`, { cwd: workDir });
+
+    const expectedNewFile: string = path.join(workDir, 'editor.out');
+    const fileContents = fs.readFileSync(expectedNewFile, 'utf8');
+    expect(fileContents.trim()).toEqual(`EDITOR ${adrDirectory}/0001-example-adr.md`);
+  });
+
+  it('should open a new ADR in the VISUAL if both VISUAL and EDITOR is supplied', () => {
+    childProcess.execSync(`EDITOR="${editorHelper}" VISUAL="${visualHelper}" ${command} new Example ADR`, { cwd: workDir });
+
+    expect(fs.existsSync(path.join(workDir, 'editor.out'))).toBeFalsy();
+
+    const expectedNewFile: string = path.join(workDir, 'visual.out');
+    const fileContents = fs.readFileSync(expectedNewFile, 'utf8');
+    expect(fileContents.trim()).toEqual(`VISUAL ${adrDirectory}/0001-example-adr.md`);
+  });
+
+});

package/tests/fake-editor

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo EDITOR "$@" > editor.out

package/tests/fake-visual

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo VISUAL "$@" > visual.out

package/tests/funny-characters.e2e.test.ts

@@ -0,0 +1,43 @@
+/* eslint-disable no-sync */
+import { describe, it, expect, afterEach, beforeEach } from 'vitest';
+import childProcess from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import { v4 as uuidv4 } from 'uuid';
+
+describe('Funny Characters', () => {
+  const workDir = path.dirname(__filename);
+  const adr: string = path.resolve(workDir, '../src/index.ts');
+  const command = `npx ts-node ${adr}`;
+  let randomDir = uuidv4();
+  let adrDirectory: string;
+
+  afterEach(() => {
+    childProcess.execSync(`rm -rf .adr-dir doc tmp ${randomDir}`, { cwd: workDir });
+  });
+
+  beforeEach(() => {
+    randomDir = uuidv4();
+    adrDirectory = path.resolve(path.join(workDir, randomDir));
+    childProcess.execSync(`${command} init ${randomDir}`, { cwd: workDir });
+  });
+
+  it('should handle titles with periods in them', async () => {
+    childProcess.execSync(`${command} new Something About Node.JS`, { cwd: workDir });
+    const expectedFile: string = path.join(adrDirectory, '0002-something-about-node-js.md');
+    expect(fs.existsSync(expectedFile)).toBeTruthy();
+  });
+
+  it('should handle titles with slashes in them', async () => {
+    childProcess.execSync(`${command} new Slash/Slash/Slash/`, { cwd: workDir });
+    const expectedFile: string = path.join(adrDirectory, '0002-slash-slash-slash.md');
+    expect(fs.existsSync(expectedFile)).toBeTruthy();
+  });
+
+  it('should handle titles with other weirdness in them', async () => {
+    childProcess.execSync(`${command} new -- "-Bar-"`, { cwd: workDir });
+    const expectedFile: string = path.join(adrDirectory, '0002-bar.md');
+    expect(fs.existsSync(expectedFile)).toBeTruthy();
+  });
+});
+

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

@@ -0,0 +1,45 @@
+/* eslint-disable no-sync */
+import { describe, it, expect, afterAll, beforeAll, vi, afterEach } from 'vitest';
+import * as childProcess from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+
+describe('Generating Graphs', () => {
+  const adr = path.resolve(path.dirname(__filename), '../src/index.ts');
+  const command = `npx ts-node ${adr}`;
+  let workDir: string;
+
+  beforeAll(async () => {
+    // @ts-ignore
+    process.env.ADR_DATE = '1992-01-12';
+    workDir = await fs.mkdtemp(path.join(os.tmpdir(), 'adr-'));
+    childProcess.execSync(`${command} init`, { cwd: workDir });
+    childProcess.execSync(`${command} new An idea that seems good at the time`, { cwd: workDir });
+    childProcess.execSync(`${command} new -s 2 A better idea`, { cwd: workDir });
+    childProcess.execSync(`${command} new This will work`, { cwd: workDir });
+    childProcess.execSync(`${command} new -s 3 The end`, { cwd: workDir });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterAll(() => {
+    childProcess.execSync(`rm -rf ${workDir}`);
+  });
+
+  it('should generate a graph', async () => {
+    const child = childProcess.execSync(`${command} generate graph`, { cwd: workDir });
+    const childContent = child.toString().trim();
+
+    expect(childContent).toMatchSnapshot();
+  });
+
+  it('should generate a graph with specified route and extension ', async () => {
+    const child = childProcess.execSync(`${command} generate graph -p http://example.com/ -e .xxx`, { cwd: workDir });
+    const childContent = child.toString().trim();
+
+    expect(childContent).toMatchSnapshot();
+  });
+});

package/tests/init-adr-repository.e2e.test.ts

@@ -0,0 +1,53 @@
+/* eslint-disable no-sync */
+import { describe, it, expect, afterEach, beforeEach } from 'vitest';
+import * as childProcess from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as os from 'os';
+
+describe('Init an ADR Repository', () => {
+  const adr = path.resolve(path.dirname(__filename), '../src/index.ts');
+  const command = `npx ts-node ${adr}`;
+
+  let adrDirectory: string;
+  let workDir: string;
+
+  beforeEach(() => {
+    // @ts-ignore
+    process.env.ADR_DATE = '1992-01-12';
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'adr-'));
+    adrDirectory = path.join(workDir, 'doc/adr');
+  });
+
+  afterEach(() => {
+    childProcess.execSync(`rm -rf ${workDir}`);
+  });
+
+  it('should use the default directory', () => {
+    childProcess.execSync(`${command} init`, { cwd: workDir });
+    const expectedFile: string = path.join(adrDirectory, '0001-record-architecture-decisions.md');
+    const expectedLockFile: string = path.join(adrDirectory, '.adr-sequence.lock');
+    expect(fs.existsSync(expectedFile)).toBeTruthy();
+    expect(fs.existsSync(expectedLockFile)).toBeTruthy();
+
+    const fileContents = fs.readFileSync(expectedFile, 'utf8');
+    const lockFileContents = fs.readFileSync(expectedLockFile, 'utf8');
+    expect(fileContents).toMatchSnapshot();
+    expect(lockFileContents).toEqual('1');
+  });
+
+  it('should use an alternate directory', () => {
+    const directory: string = path.resolve(path.join(workDir, 'tmp', 'alternative-dir'));
+    childProcess.execSync(`${command} init ${directory}`, { cwd: workDir });
+
+    const expectedInitFile: string = path.join(directory, '0001-record-architecture-decisions.md');
+    const expectedLockFile: string = path.join(directory, '.adr-sequence.lock');
+    expect(fs.existsSync(expectedInitFile)).toBeTruthy();
+    expect(fs.existsSync(expectedLockFile)).toBeTruthy();
+
+    const fileContents = fs.readFileSync(expectedInitFile, 'utf8');
+    const lockFileContents = fs.readFileSync(expectedLockFile, 'utf8');
+    expect(fileContents).toMatchSnapshot();
+    expect(lockFileContents).toEqual('1');
+  });
+});