@meza/adr-tools 1.0.1

package/.adr-dir

@@ -0,0 +1 @@
+doc/adr

package/.editorconfig

@@ -0,0 +1,13 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+charset = utf-8
+insert_final_newline = true
+end_of_line = lf
+indent_size = 2
+indent_style = space
+trim_trailing_whitespace = true

package/.eslintignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/.eslintrc.json

@@ -0,0 +1,23 @@
+{
+  "extends": [
+    "tailored-tunes",
+    "plugin:json/recommended",
+    "plugin:security/recommended"
+  ],
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": [
+    "json",
+    "@typescript-eslint"
+  ],
+  "rules": {
+    "no-console": "off",
+    "security/detect-object-injection": 0,
+    "security/detect-non-literal-fs-filename": 0
+  },
+  "env": {
+    "commonjs": false,
+    "es6": true,
+    "node": true
+  }
+}

package/.github/dependabot.yml

@@ -0,0 +1,14 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    versioning-strategy: increase-if-necessary
+    commit-message:
+      prefix: "chore: "
+    schedule:
+      interval: "daily"

package/.github/stale.yml

@@ -0,0 +1,18 @@
+# Number of days of inactivity before an issue becomes stale
+daysUntilStale: 90
+# Number of days of inactivity before a stale issue is closed
+daysUntilClose: 275
+# Issues with these labels will never be considered stale
+exemptLabels:
+  - pinned
+  - security
+# Label to use when marking an issue as stale
+staleLabel: stale
+# Comment to post when marking an issue as stale. Set to `false` to disable
+markComment: >
+  This issue has been automatically marked as stale because it has not had
+  recent activity. It will be closed if no further activity occurs. Thank you
+  for your contributions.
+# Comment to post when closing a stale issue. Set to `false` to disable
+closeComment: >
+  This issue has been automatically closed because it has not had recent activity.

package/.github/workflows/auto-merge.yml

@@ -0,0 +1,14 @@
+name: auto-merge dependabot
+
+on:
+  pull_request:
+
+jobs:
+  auto-merge:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ahmadnassri/action-dependabot-auto-merge@v2
+        with:
+          target: minor # includes patch updates!
+          github-token: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/ci.yml

@@ -0,0 +1,89 @@
+name: Verify and Release
+
+on: [push]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [ 18.x ]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Cache multiple paths
+        uses: actions/cache@v2
+        with:
+          path: |
+            ~/.cache
+            ~/node_modules
+          key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
+
+      - name: Get yarn cache directory path
+        id: yarn-cache-dir-path
+        run: echo "::set-output name=dir::$(yarn config get cacheFolder)"
+
+      - uses: actions/cache@v2
+        id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
+        with:
+          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'yarn'
+
+      - run: yarn --pure-lockfile
+      - run: yarn lint
+
+  release:
+    needs: [build]
+    name: Release
+    runs-on: ubuntu-latest
+    if: ${{github.ref == 'ref/head/main'}} || ${{github.ref == 'ref/head/next'}}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Cache multiple paths
+        uses: actions/cache@v2
+        with:
+          path: |
+            ~/.cache
+            ~/node_modules
+          key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
+
+      - name: Get yarn cache directory path
+        id: yarn-cache-dir-path
+        run: echo "::set-output name=dir::$(yarn config get cacheFolder)"
+
+      - uses: actions/cache@v2
+        id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
+        with:
+          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'yarn'
+
+      - run: yarn --pure-lockfile --offline
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: yarn release

package/.husky/commit-msg

@@ -0,0 +1,4 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npx --no -- commitlint --edit "${1}"

package/.releaserc.json

@@ -0,0 +1,41 @@
+{
+  "plugins": [
+    "@semantic-release/npm",
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "docs/CHANGELOG.md"
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": [
+          "CHANGELOG.md"
+        ]
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["CHANGELOG.md"]
+      }
+    ],
+    [
+      "@semantic-release/github",
+      {
+        "assets": [
+          {
+            "path": [
+              "dist/**",
+              "CHANGELOG.md"
+            ],
+            "name": "adr-tools-${nextRelease.gitTag}.zip",
+            "label": "ADR-Tools ${nextRelease.gitTag}"
+          }
+        ]
+    }]
+  ]
+}

package/README.md

@@ -0,0 +1,30 @@
+# ADR-TOOLS
+
+> THIS REPO IS UNDER HEAVY DEVELOPMENT. CODE YOU SEE HERE IS... NOT QUITE READY OR PRETTY (yet).
+
+This is a Typescript fork of Nat Pryce's [ADR-TOOLS](https://github.com/npryce/adr-tools).
+
+There are a few other forks out there which do some parts of the original tool but none actually do it fully.
+
+This does.
+
+More documentation to follow very soon!
+
+## Conventions
+
+An ADR file MUST have a `# title` at the top and a `## Status` header.
+
+## Local Development
+
+`yarn install`
+
+### Commits
+
+This project uses conventional commits. See [conventional-commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+There are git hooks that check the commit messages and enforce the commit rules.
+There is a helper tool to make it easier to create commits when unfamiliar with the rules:
+
+`yarn commit`
+
+This will use the [commitlint prompt tool](https://commitlint.js.org/#/guides-use-prompt) to help you create commits.

package/doc/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,21 @@
+# 1. Record architecture decisions
+
+Date: 2022-06-22
+
+## 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](http://thinkrelevance.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/doc/adr/0002-using-heavy-e2e-tests.md

@@ -0,0 +1,20 @@
+# 2. Using Heavy E2E Tests
+
+Date: 2022-06-22
+
+## Status
+
+Accepted
+
+## Context
+
+The original tool has an [exhaustive test suite](https://github.com/npryce/adr-tools/tree/master/tests) that allows us to make sure that we're backwards compatible.
+
+## Decision
+
+We'll be re-implementing those tests for ourselves too. This means that we will be using the original examples,
+expectations and the ethos of invoking the tool with the given examples.
+
+## Consequences
+
+The E2E test suite will be very slow to run and it can only be executed sequentially.

package/docs/CHANGELOG.md

@@ -0,0 +1,6 @@
+## [1.0.1](https://github.com/meza/adr-tools/compare/v1.0.0...v1.0.1) (2022-06-27)
+
+
+### Bug Fixes
+
+* fixed deployment restrictions [#27](https://github.com/meza/adr-tools/issues/27) ([af4f4cc](https://github.com/meza/adr-tools/commit/af4f4cc2b208ff696baddad1bda0563170bfe1ce))

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@meza/adr-tools",
+  "version": "1.0.1",
+  "main": "dist/index.js",
+  "bin": {
+    "adr": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "dist/index.d.ts",
+  "private": false,
+  "scripts": {
+    "prebuild": "node -p \"'export const LIB_VERSION = ' + require('./package.json').version + ';'\" > src/version.ts",
+    "build": "tsc",
+    "start": "ts-node src/index.ts",
+    "commit": "commit",
+    "ci": "npm set editor '' && yarn lint && yarn test",
+    "ci:dev": "exit 0",
+    "clean": "rm -rf dist .cache/tsbuildinfo",
+    "clean:all": "yarn clean && rm -rf node_modules .cache",
+    "lint:eslint": "eslint . --ext .ts --ext .json --cache --cache-location .cache/",
+    "lint:tsc": "tsc --noEmit",
+    "lint:fix": "yarn lint:eslint --fix && yarn lint:tsc",
+    "lint": "yarn lint:eslint && yarn lint:tsc",
+    "test": "vitest",
+    "prepare": "husky install",
+    "report": "exit 0",
+    "semantic-release": "semantic-release",
+    "release": "semantic-release"
+  },
+  "dependencies": {
+    "@types/inquirer": "^8.2.1",
+    "@types/marked": "^4.0.3",
+    "@types/node": "^18.0.0",
+    "chalk": "^4.1.2",
+    "commander": "^9.3.0",
+    "core-js": "^3.19.1",
+    "inquirer": "^8.2.4",
+    "marked": "^4.0.17"
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "husky": {
+    "hooks": {
+      "post-merge": "install-deps-postmerge",
+      "pre-push": "yarn ci",
+      "pre-commit": "yarn lint",
+      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+    }
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^17.0.2",
+    "@commitlint/config-conventional": "^17.0.2",
+    "@commitlint/prompt-cli": "^17.0.0",
+    "@meza/tsconfig-base": "^1.1.0",
+    "@release-it/conventional-changelog": "^5.0.0",
+    "@semantic-release/changelog": "^6.0.1",
+    "@semantic-release/commit-analyzer": "^9.0.2",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^8.0.4",
+    "@semantic-release/npm": "^9.0.1",
+    "@semantic-release/release-notes-generator": "^10.0.3",
+    "@types/uuid": "^8.3.4",
+    "@typescript-eslint/eslint-plugin": "^5.29.0",
+    "@typescript-eslint/parser": "^5.3.0",
+    "@vitest/ui": "^0.15.2",
+    "c8": "^7.11.3",
+    "eslint": "^8.1.0",
+    "eslint-config-tailored-tunes": "^5.0.2",
+    "eslint-plugin-json": "^3.1.0",
+    "eslint-plugin-security": "^1.5.0",
+    "husky": "^8.0.1",
+    "install-deps-postmerge": "^2.0.1",
+    "mock-cwd": "^1.0.0",
+    "semantic-release": "^19.0.3",
+    "standard-version": "^9.3.2",
+    "ts-node": "^10.8.1",
+    "typescript": "^4.4.4",
+    "uuid": "^8.3.2",
+    "vitest": "^0.15.2",
+    "yarn": "^1.22.17"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/meza/adr-tools.git"
+  }
+}

package/src/environment.d.ts

@@ -0,0 +1,14 @@
+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/index.ts

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { LIB_VERSION } from './version';
+import { generateToc, init, link, listAdrs, newAdr } from './lib/adr';
+import chalk from 'chalk';
+import { workingDir } from './lib/config';
+import * as path from 'path';
+import { getLinksFrom, getTitleFrom } from './lib/manipulator';
+import fs from 'fs/promises';
+
+const program = new Command();
+
+const collectLinks = (val: string, memo: string[]) => {
+  memo.push(val);
+  return memo;
+};
+
+const collectSupersedes = (val: string, memo: string[]) => {
+  memo.push(val);
+  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`;
+    }
+  }
+  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`;
+      }
+    }
+
+  }
+
+  text += '}\n';
+  console.log(text);
+};
+
+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 });
+    }
+  });
+
+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('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('list').action(async () => {
+  const adrs = await listAdrs();
+  console.log(adrs.map(adr => path.relative(workingDir(), adr)).join('\n'));
+});
+
+program.parse();
+