feat(ADR): implement ADR plugin

Signed-off-by: Phil Kuang <pkuang@factset.com>

plugins/adr-common/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/adr-common/README.md

@@ -0,0 +1,3 @@
+# ADR Common
+
+Common types and functionalities for the ADR plugin.

plugins/adr-common/api-report.md

@@ -0,0 +1,36 @@
+## API Report File for "@backstage/plugin-adr-common"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { Entity } from '@backstage/catalog-model';
+import { IndexableDocument } from '@backstage/plugin-search-common';
+import { ScmIntegrationRegistry } from '@backstage/integration';
+
+// @public
+export interface AdrDocument extends IndexableDocument {
+  date?: string;
+  status?: string;
+}
+
+// @public
+export type AdrFilePathFilterFn = (path: string) => boolean;
+
+// @public
+export const ANNOTATION_ADR_LOCATION = 'backstage.io/adr-location';
+
+// @public
+export const getAdrLocationUrl: (
+  entity: Entity,
+  scmIntegration: ScmIntegrationRegistry,
+) => string;
+
+// @public
+export const isAdrAvailable: (entity: Entity) => boolean;
+
+// @public
+export const MADR_DATE_FORMAT = 'yyyy-MM-dd';
+
+// @public
+export const madrFilePathFilter: AdrFilePathFilterFn;
+```

plugins/adr-common/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@backstage/plugin-adr-common",
+  "description": "Common functionalities for the adr plugin",
+  "version": "0.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "module": "dist/index.esm.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "common-library"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "plugins/adr-common"
+  },
+  "scripts": {
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "dependencies": {
+    "@backstage/catalog-model": "^1.0.1",
+    "@backstage/integration": "^1.2.0-next.0",
+    "@backstage/plugin-search-common": "^0.3.3"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.17.1-next.0"
+  },
+  "files": [
+    "dist"
+  ]
+}

plugins/adr-common/src/index.ts

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Common types and functionalities for the ADR plugin.
+ * @packageDocumentation
+ */
+import { Entity, getEntitySourceLocation } from '@backstage/catalog-model';
+import { IndexableDocument } from '@backstage/plugin-search-common';
+import { ScmIntegrationRegistry } from '@backstage/integration';
+
+/**
+ * ADR plugin annotation.
+ * @public
+ */
+export const ANNOTATION_ADR_LOCATION = 'backstage.io/adr-location';
+
+/**
+ * Standard luxon DateTime format string for MADR dates.
+ * @public
+ */
+export const MADR_DATE_FORMAT = 'yyyy-MM-dd';
+
+/**
+ * Utility function to get the value of an entity ADR annotation.
+ * @public
+ */
+const getAdrLocationDir = (entity: Entity) =>
+  entity.metadata.annotations?.[ANNOTATION_ADR_LOCATION]?.trim();
+
+/**
+ * Utility function to determine if the given entity has ADRs.
+ * @public
+ */
+export const isAdrAvailable = (entity: Entity) =>
+  Boolean(getAdrLocationDir(entity));
+
+/**
+ * Utility function to extract the ADR location URL from an entity based off
+ * its ADR annotation and relative to the entity source location.
+ * @public
+ */
+export const getAdrLocationUrl = (
+  entity: Entity,
+  scmIntegration: ScmIntegrationRegistry,
+) => {
+  if (!isAdrAvailable(entity)) {
+    throw new Error(`Missing ADR annotation: ${ANNOTATION_ADR_LOCATION}`);
+  }
+
+  return scmIntegration.resolveUrl({
+    url: getAdrLocationDir(entity)!,
+    base: getEntitySourceLocation(entity).target,
+  });
+};
+
+/**
+ * File path filter function type for ADR filenames
+ * @public
+ */
+export type AdrFilePathFilterFn = (path: string) => boolean;
+
+/**
+ * File path filter for MADR filename formats
+ * @public
+ */
+export const madrFilePathFilter: AdrFilePathFilterFn = (path: string) =>
+  /^\d{4}-.+\.md$/.test(path);
+
+/**
+ * ADR indexable document interface
+ * @public
+ */
+export interface AdrDocument extends IndexableDocument {
+  /**
+   * ADR status label
+   */
+  status?: string;
+  /**
+   * ADR date
+   */
+  date?: string;
+}