Merge pull request #17954 from brianphillips/madr-v3-front-matter

MADR v3 Front Matter parsing/display

.changeset/nine-bags-dream.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-adr': patch
+---
+
+Render table of front matter metadata when displaying MADR v3 formatted ADR

.changeset/real-donuts-brush.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-adr-backend': patch
+---
+
+Use front matter parser for MADR v3 formatted ADRs when indexing status/date

.changeset/strange-geese-argue.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-adr-common': patch
+---
+
+Add utility function for parsing MADR front matter

app-config.yaml

@@ -274,6 +274,9 @@ catalog:
     # Example component for TechDocs
     - type: file
       target: ../../plugins/techdocs-backend/examples/documented-component/catalog-info.yaml
+    # Example component for ADRs
+    - type: file
+      target: ../../plugins/adr/examples/component/catalog-info.yaml
     # Backstage example templates
     - type: file
       target: ../../plugins/scaffolder-backend/sample-templates/all-templates.yaml

packages/app/package.json

@@ -15,6 +15,7 @@
     "@backstage/core-components": "workspace:^",
     "@backstage/core-plugin-api": "workspace:^",
     "@backstage/integration-react": "workspace:^",
+    "@backstage/plugin-adr": "workspace:^",
     "@backstage/plugin-airbrake": "workspace:^",
     "@backstage/plugin-apache-airflow": "workspace:^",
     "@backstage/plugin-api-docs": "workspace:^",

packages/app/src/components/catalog/EntityPage.tsx

@@ -26,6 +26,7 @@ import {
   RELATION_PROVIDES_API,
 } from '@backstage/catalog-model';
 import { EmptyState, InfoCard } from '@backstage/core-components';
+import { EntityAdrContent, isAdrAvailable } from '@backstage/plugin-adr';
 import {
   EntityApiDefinitionCard,
   EntityConsumedApisCard,
@@ -484,6 +485,10 @@ const serviceEntityPage = (
       {techdocsContent}
     </EntityLayout.Route>
 
+    <EntityLayout.Route if={isAdrAvailable} path="/adrs" title="ADRS">
+      <EntityAdrContent />
+    </EntityLayout.Route>
+
     <EntityLayout.Route
       if={isNewRelicDashboardAvailable}
       path="/newrelic-dashboard"

packages/app/src/components/search/SearchPage.tsx

@@ -28,6 +28,7 @@ import {
   catalogApiRef,
   CATALOG_FILTER_EXISTS,
 } from '@backstage/plugin-catalog-react';
+import { AdrSearchResultListItem } from '@backstage/plugin-adr';
 import { SearchType } from '@backstage/plugin-search';
 import {
   SearchBar,
@@ -86,6 +87,11 @@ const SearchPage = () => {
                     name: 'Documentation',
                     icon: <DocsIcon />,
                   },
+                  {
+                    value: 'adr',
+                    name: 'Architecture Decision Records',
+                    icon: <DocsIcon />,
+                  },
                 ]}
               />
               <Paper className={classes.filters}>
@@ -131,6 +137,7 @@ const SearchPage = () => {
               <CatalogSearchResultListItem icon={<CatalogIcon />} />
               <TechDocsSearchResultListItem icon={<DocsIcon />} />
               <ToolSearchResultListItem icon={<BuildIcon />} />
+              <AdrSearchResultListItem icon={<DocsIcon />} />
             </SearchResult>
             <SearchResultPager />
           </Grid>

packages/backend/src/plugins/search.ts

@@ -15,6 +15,7 @@
  */
 
 import { useHotCleanup } from '@backstage/backend-common';
+import { DefaultAdrCollatorFactory } from '@backstage/plugin-adr-backend';
 import { DefaultCatalogCollatorFactory } from '@backstage/plugin-catalog-backend';
 import { ToolDocumentCollatorFactory } from '@backstage/plugin-explore-backend';
 import { createRouter } from '@backstage/plugin-search-backend';
@@ -68,6 +69,18 @@ export default async function createPlugin(
 
   // Collators are responsible for gathering documents known to plugins. This
   // particular collator gathers entities from the software catalog.
+  indexBuilder.addCollator({
+    schedule,
+    factory: DefaultAdrCollatorFactory.fromConfig({
+      cache: env.cache,
+      config: env.config,
+      discovery: env.discovery,
+      logger: env.logger,
+      reader: env.reader,
+      tokenManager: env.tokenManager,
+    }),
+  });
+
   indexBuilder.addCollator({
     schedule,
     factory: DefaultCatalogCollatorFactory.fromConfig(env.config, {

plugins/adr-backend/src/search/madrParser.ts

@@ -16,7 +16,10 @@
 
 import { DateTime } from 'luxon';
 import { marked } from 'marked';
-import { MADR_DATE_FORMAT } from '@backstage/plugin-adr-common';
+import {
+  MADR_DATE_FORMAT,
+  parseMadrWithFrontmatter,
+} from '@backstage/plugin-adr-common';
 
 const getTitle = (tokens: marked.TokensList): string | undefined => {
   return (
@@ -26,22 +29,6 @@ const getTitle = (tokens: marked.TokensList): string | undefined => {
   )?.text;
 };
 
-const getStatusForV3Format = (tokens: marked.TokensList): string | undefined =>
-  (
-    tokens.find(
-      t =>
-        t.type === 'heading' &&
-        t.depth === 2 &&
-        t.text.toLowerCase().includes('status:'),
-    ) as marked.Tokens.Text
-  )?.text
-    .toLowerCase()
-    .split('\n')
-    .find(l => /^status:/.test(l))
-    ?.replace(/^status:/i, '')
-    .trim()
-    .toLocaleLowerCase('en-US');
-
 const getStatusForV2Format = (tokens: marked.TokensList): string | undefined =>
   (tokens.find(t => t.type === 'list') as marked.Tokens.List)?.items
     ?.find(t => /^status:/i.test(t.text))
@@ -49,71 +36,45 @@ const getStatusForV2Format = (tokens: marked.TokensList): string | undefined =>
     .trim()
     .toLocaleLowerCase('en-US');
 
-const getDateForV3Format = (
-  tokens: marked.TokensList,
-  dateFormat: string,
-): string | undefined => {
-  let adrDateTime: DateTime | undefined;
-  const dateLine = (
-    tokens.find(
-      t =>
-        t.type === 'heading' &&
-        t.depth === 2 &&
-        t.text.toLowerCase().includes('date:'),
-    ) as marked.Tokens.Text
-  )?.text
-    .toLowerCase()
-    .split('\n')
-    .find(l => /^date:/.test(l));
-
-  if (dateLine) {
-    adrDateTime = DateTime.fromFormat(
-      dateLine.replace(/^date:/i, '').trim(),
-      dateFormat,
-    );
-  }
-  return adrDateTime?.isValid
-    ? adrDateTime.toFormat(MADR_DATE_FORMAT)
-    : undefined;
-};
-
-const getDateForV2Format = (
-  tokens: marked.TokensList,
-  dateFormat: string,
-): string | undefined => {
+const getDateForV2Format = (tokens: marked.TokensList): string | undefined => {
   const listTokens = (tokens.find(t => t.type === 'list') as marked.Tokens.List)
     ?.items;
-  const adrDateTime = DateTime.fromFormat(
-    listTokens
-      ?.find(t => /^date:/i.test(t.text))
-      ?.text.replace(/^date:/i, '')
-      .trim() ?? '',
-    dateFormat,
-  );
-  return adrDateTime?.isValid
-    ? adrDateTime.toFormat(MADR_DATE_FORMAT)
-    : undefined;
+  const adrDateTime = listTokens
+    ?.find(t => /^date:/i.test(t.text))
+    ?.text.replace(/^date:/i, '')
+    .trim();
+  return adrDateTime;
 };
 
-const getStatus = (tokens: marked.TokensList): string | undefined => {
-  return getStatusForV3Format(tokens) ?? getStatusForV2Format(tokens);
+const getStatus = (
+  tokens: marked.TokensList,
+  frontMatterStatus?: string,
+): string | undefined => {
+  return frontMatterStatus ?? getStatusForV2Format(tokens);
 };
 const getDate = (
   tokens: marked.TokensList,
   dateFormat: string,
-): string | undefined =>
-  getDateForV3Format(tokens, dateFormat) ??
-  getDateForV2Format(tokens, dateFormat);
+  frontMatterDate?: string,
+): string | undefined => {
+  const dateString = frontMatterDate ?? getDateForV2Format(tokens);
+  if (!dateString) {
+    return undefined;
+  }
+  const date = DateTime.fromFormat(dateString, dateFormat);
+  return date?.isValid ? date.toFormat(MADR_DATE_FORMAT) : undefined;
+};
 
 export const madrParser = (content: string, dateFormat = MADR_DATE_FORMAT) => {
-  const tokens = marked.lexer(content);
+  const preparsed = parseMadrWithFrontmatter(content);
+  const tokens = marked.lexer(preparsed.content);
   if (!tokens.length) {
     throw new Error('ADR has no content');
   }
 
   return {
     title: getTitle(tokens),
-    status: getStatus(tokens),
-    date: getDate(tokens, dateFormat),
+    status: getStatus(tokens, preparsed.status),
+    date: getDate(tokens, dateFormat, preparsed.date),
   };
 };

plugins/adr-common/api-report.md

@@ -35,4 +35,15 @@ export const MADR_DATE_FORMAT = 'yyyy-MM-dd';
 
 // @public
 export const madrFilePathFilter: AdrFilePathFilterFn;
+
+// @public
+export interface ParsedMadr {
+  attributes: Record<string, unknown>;
+  content: string;
+  date?: string;
+  status?: string;
+}
+
+// @public
+export const parseMadrWithFrontmatter: (content: string) => ParsedMadr;
 ```

plugins/adr-common/package.json

@@ -31,7 +31,8 @@
   "dependencies": {
     "@backstage/catalog-model": "workspace:^",
     "@backstage/integration": "workspace:^",
-    "@backstage/plugin-search-common": "workspace:^"
+    "@backstage/plugin-search-common": "workspace:^",
+    "front-matter": "^4.0.2"
   },
   "devDependencies": {
     "@backstage/cli": "workspace:^"

plugins/adr-common/src/index.ts

@@ -20,6 +20,7 @@
 import { Entity, getEntitySourceLocation } from '@backstage/catalog-model';
 import { IndexableDocument } from '@backstage/plugin-search-common';
 import { ScmIntegrationRegistry } from '@backstage/integration';
+import frontMatter from 'front-matter';
 
 /**
  * ADR plugin annotation.
@@ -101,3 +102,43 @@ export interface AdrDocument extends IndexableDocument {
    */
   date?: string;
 }
+
+/**
+ * Parsed MADR document with front matter (if present) parsed and extracted from the main markdown content.
+ * @public
+ */
+export interface ParsedMadr {
+  /**
+   * Main body of ADR content (with any front matter removed)
+   */
+  content: string;
+  /**
+   * ADR status
+   */
+  status?: string;
+  /**
+   * ADR date
+   */
+  date?: string;
+  /**
+   * All attributes parsed from front matter
+   */
+  attributes: Record<string, unknown>;
+}
+
+/**
+ * Utility function to parse raw markdown content for an ADR and extract any metadata found as "front matter" at the top of the Markdown document.
+ * @param content - Raw markdown content which may (optionally) include front matter
+ * @public
+ */
+export const parseMadrWithFrontmatter = (content: string): ParsedMadr => {
+  const parsed = frontMatter<Record<string, unknown>>(content);
+  const status = parsed.attributes.status;
+  const date = parsed.attributes.date;
+  return {
+    content: parsed.body,
+    status: status ? String(status) : undefined,
+    date: date ? String(date) : undefined,
+    attributes: parsed.attributes,
+  };
+};

plugins/adr/README.md

@@ -113,7 +113,7 @@ import { AdrDocument } from '@backstage/plugin-adr-common';
 
 ## Custom ADR formats
 
-By default, this plugin will parse ADRs according to the format specified by the [Markdown Architecture Decision Record (MADR) v2.x template](https://github.com/adr/madr/tree/2.1.2). If your ADRs are written using a different format, you can apply the following customizations to correctly identify and parse your documents:
+By default, this plugin will parse ADRs according to the format specified by the [Markdown Architecture Decision Record (MADR) v2.x template](https://github.com/adr/madr/tree/2.1.2) or the [Markdown Any Decision Record (MADR) 3.x template](https://github.com/adr/madr/tree/3.0.0). If your ADRs are written using a different format, you can apply the following customizations to correctly identify and parse your documents:
 
 ### Custom Filename/Path Format
 
@@ -135,7 +135,7 @@ const myCustomFilterFn: AdrFilePathFilterFn = (path: string): boolean => {
 
 ### Custom Content Decorators
 
-Your ADR Markdown content will typically be rendered in the UI as is with the exception of relative links/embeds being rewritten as absolute URLs so they can be linked correctly (e.g. `./my-diagram.png` => `<ABSOLUTE_ADR_DIR_URL>/my-diagram.png`). Depending on your ADR format, you may want to apply additional transformations to the content (e.g. parsing/ignoring front matter). You can do so by passing in a list of custom content decorators for the optional `contentDecorators` parameter. Note that passing in this parameter will override the default decorators. If you want to include the default ones, make sure to add them as well:
+Your ADR Markdown content will typically be rendered in the UI as is with the exception of relative links/embeds being rewritten as absolute URLs so they can be linked correctly (e.g. `./my-diagram.png` => `<ABSOLUTE_ADR_DIR_URL>/my-diagram.png`). Depending on your ADR format, you may want to apply additional transformations to the content (e.g. hiding or formatting front matter in a different way). You can do so by passing in a list of custom content decorators for the optional `contentDecorators` parameter. Note that passing in this parameter will override the default decorators. If you want to include the default ones, make sure to add them as well:
 
 ```tsx
 import {
@@ -154,6 +154,7 @@ const myCustomDecorator: AdrContentDecorator = ({ content }) => {
 <EntityAdrContent contentDecorators={[
     AdrReader.decorators.createRewriteRelativeLinksDecorator(),
     AdrReader.decorators.createRewriteRelativeEmbedsDecorator(),
+    AdrReader.decorators.createFrontMatterFormatterDecorator(),
     myCustomDecorator,
   ]}
 />

plugins/adr/api-report.md

@@ -80,6 +80,7 @@ export const AdrReader: {
   decorators: Readonly<{
     createRewriteRelativeLinksDecorator(): AdrContentDecorator;
     createRewriteRelativeEmbedsDecorator(): AdrContentDecorator;
+    createFrontMatterFormatterDecorator(): AdrContentDecorator;
   }>;
 };
 

plugins/adr/examples/component/catalog-info.yaml

@@ -0,0 +1,13 @@
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: component-with-adrs
+  title: Component With ADRs
+  description: A Service with ADRs registerd
+  annotations:
+    backstage.io/adr-location: https://github.com/adr/madr/tree/develop/docs/decisions
+spec:
+  type: service
+  lifecycle: experimental
+  owner: user:guest

plugins/adr/src/components/AdrReader/AdrReader.tsx

@@ -59,6 +59,7 @@ export const AdrReader = (props: {
     const adrDecorators = decorators ?? [
       adrDecoratorFactories.createRewriteRelativeLinksDecorator(),
       adrDecoratorFactories.createRewriteRelativeEmbedsDecorator(),
+      adrDecoratorFactories.createFrontMatterFormatterDecorator(),
     ];
 
     return adrDecorators.reduce(

plugins/adr/src/components/AdrReader/decorators.ts

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { parseMadrWithFrontmatter } from '@backstage/plugin-adr-common';
 import { AdrContentDecorator } from './types';
 
 /**
@@ -44,4 +45,23 @@ export const adrDecoratorFactories = Object.freeze({
       ),
     });
   },
+  /**
+   * Formats YAML front-matter into a table format (if any exists in the markdown document)
+   */
+  createFrontMatterFormatterDecorator(): AdrContentDecorator {
+    return ({ content }) => {
+      const parsedFrontmatter = parseMadrWithFrontmatter(content);
+      let table = '';
+      const attrs = parsedFrontmatter.attributes;
+      if (Object.keys(attrs).length > 0) {
+        const stripNewLines = (val: unknown) =>
+          String(val).replaceAll('\n', '<br/>');
+        const row = (vals: string[]) => `|${vals.join('|')}|\n`;
+        table = `${row(Object.keys(attrs))}`;
+        table += `${row(Object.keys(attrs).map(() => '---'))}`;
+        table += `${row(Object.values(attrs).map(stripNewLines))}\n\n`;
+      }
+      return { content: table + parsedFrontmatter.content };
+    };
+  },
 });

yarn.lock

@@ -4553,10 +4553,11 @@ __metadata:
     "@backstage/cli": "workspace:^"
     "@backstage/integration": "workspace:^"
     "@backstage/plugin-search-common": "workspace:^"
+    front-matter: ^4.0.2
   languageName: unknown
   linkType: soft
 
-"@backstage/plugin-adr@workspace:plugins/adr":
+"@backstage/plugin-adr@workspace:^, @backstage/plugin-adr@workspace:plugins/adr":
   version: 0.0.0-use.local
   resolution: "@backstage/plugin-adr@workspace:plugins/adr"
   dependencies:
@@ -24345,6 +24346,7 @@ __metadata:
     "@backstage/core-components": "workspace:^"
     "@backstage/core-plugin-api": "workspace:^"
     "@backstage/integration-react": "workspace:^"
+    "@backstage/plugin-adr": "workspace:^"
     "@backstage/plugin-airbrake": "workspace:^"
     "@backstage/plugin-apache-airflow": "workspace:^"
     "@backstage/plugin-api-docs": "workspace:^"
@@ -25482,6 +25484,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"front-matter@npm:^4.0.2":
+  version: 4.0.2
+  resolution: "front-matter@npm:4.0.2"
+  dependencies:
+    js-yaml: ^3.13.1
+  checksum: a5b4c36d75a820301ebf31db0f677332d189c4561903ab6853eaa0504b43634f98557dbf87752e09043dbd2c9dcc14b4bcf9151cb319c8ad7e26edb203c0cd23
+  languageName: node
+  linkType: hard
+
 "fs-constants@npm:^1.0.0":
   version: 1.0.0
   resolution: "fs-constants@npm:1.0.0"