paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 43 Packages Projects Releases Wiki Activity

feat: improve navigation of adr plugin

Browse Source 
Signed-off-by: David Weber <david.weber@w3tec.ch>
This commit is contained in:
David Weber
2023-01-29 01:30:46 +01:00
parent 11b3769c19
commit 0a32911d8a
10 changed files with 136 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/light-crabs-drum.md
+6
View File
@@ -0,0 +1,6 @@
---
'@backstage/plugin-adr-backend': minor
'@backstage/plugin-adr': minor
---
Display title, status and date in ADR navigation, sourced from ADR content and reverse order.
plugins/adr-backend/src/search/createMadrParser.ts
+5 -37
View File
@@ -14,12 +14,11 @@
* limitations under the License.
*/
import { DateTime } from 'luxon';
import { marked } from 'marked';
import { stringifyEntityRef } from '@backstage/catalog-model';
import { MADR_DATE_FORMAT } from '@backstage/plugin-adr-common';
import { AdrParser } from './types';
import { madrParser } from './madrParser';
const applyArgsToFormat = (
format: string,
@@ -65,43 +64,12 @@ export const createMadrParser = (
const dateFormat = options.dateFormat ?? MADR_DATE_FORMAT;
return async ({ entity, content, path }) => {
const tokens = marked.lexer(content);
if (!tokens.length) {
throw new Error('ADR has no content');
}
// First h1 header should contain ADR title
const adrTitle = (
tokens.find(
t => t.type === 'heading' && t.depth === 1,
) as marked.Tokens.Heading
)?.text;
// First list should contain status & date metadata (if defined)
const listTokens = (
tokens.find(t => t.type === 'list') as marked.Tokens.List
)?.items;
const adrStatus = listTokens
.find(t => /^status:/i.test(t.text))
?.text.replace(/^status:/i, '')
.trim()
.toLocaleLowerCase('en-US');
const adrDateTime = DateTime.fromFormat(
listTokens
.find(t => /^date:/i.test(t.text))
?.text.replace(/^date:/i, '')
.trim() ?? '',
dateFormat,
);
const adrDate = adrDateTime.isValid
? adrDateTime.toFormat(MADR_DATE_FORMAT)
: undefined;
const madr = madrParser(content, dateFormat);
return {
title: adrTitle ?? path.replace(/\.md$/, ''),
title: madr.title ?? path.replace(/\.md$/, ''),
text: content,
status: adrStatus,
date: adrDate,
status: madr.status,
date: madr.date,
entityRef: stringifyEntityRef(entity),
entityTitle: entity.metadata.title,
location: applyArgsToFormat(locationTemplate, {
plugins/adr-backend/src/search/madrParser.ts
+59
View File
@@ -0,0 +1,59 @@
/*
* Copyright 2023 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.
*/
import { DateTime } from 'luxon';
import { marked } from 'marked';
import { MADR_DATE_FORMAT } from '@backstage/plugin-adr-common';
export const madrParser = (content: string, dateFormat = MADR_DATE_FORMAT) => {
const tokens = marked.lexer(content);
if (!tokens.length) {
throw new Error('ADR has no content');
}
// First h1 header should contain ADR title
const adrTitle = (
tokens.find(
t => t.type === 'heading' && t.depth === 1,
) as marked.Tokens.Heading
)?.text;
// First list should contain status & date metadata (if defined)
const listTokens = (tokens.find(t => t.type === 'list') as marked.Tokens.List)
?.items;
const adrStatus = listTokens
?.find(t => /^status:/i.test(t.text))
?.text.replace(/^status:/i, '')
.trim()
.toLocaleLowerCase('en-US');
const adrDateTime = DateTime.fromFormat(
listTokens
?.find(t => /^date:/i.test(t.text))
?.text.replace(/^date:/i, '')
.trim() ?? '',
dateFormat,
);
const adrDate = adrDateTime?.isValid
? adrDateTime.toFormat(MADR_DATE_FORMAT)
: undefined;
return {
title: adrTitle,
status: adrStatus,
date: adrDate,
};
};
plugins/adr-backend/src/service/router.test.ts
+4 -4
View File
@@ -156,8 +156,8 @@ describe('createRouter', () => {
data: [
{
type: 'file',
name: 'testFile001.txt',
path: 'folder/testFile001.txt',
name: 'testFile002.txt',
path: 'testFile002.txt',
},
{
type: 'file',
@@ -166,8 +166,8 @@ describe('createRouter', () => {
},
{
type: 'file',
name: 'testFile002.txt',
path: 'testFile002.txt',
name: 'testFile001.txt',
path: 'folder/testFile001.txt',
},
],
};
plugins/adr-backend/src/service/router.ts
+15 -7
View File
@@ -19,6 +19,7 @@ import { NotModifiedError, stringifyError } from '@backstage/errors';
import { Logger } from 'winston';
import express from 'express';
import Router from 'express-promise-router';
import { madrParser } from '../search/madrParser';
/** @public */
export type AdrRouterOptions = {
@@ -59,13 +60,20 @@ export async function createRouter(
etag: cachedTree?.etag,
});
const files = await treeGetResponse.files();
const data = files.map(file => {
return {
type: 'file',
name: file.path.substring(file.path.lastIndexOf('/') + 1),
path: file.path,
};
});
const data = await Promise.all(
files
.map(async file => {
const fileContent = await file.content();
const adrInfo = madrParser(fileContent.toString());
return {
type: 'file',
name: file.path.substring(file.path.lastIndexOf('/') + 1),
path: file.path,
...adrInfo,
};
})
.reverse(),
);
await cacheClient.set(urlToProcess, {
data,
plugins/adr/README.md
+2
View File
@@ -4,6 +4,8 @@ Welcome to the ADR plugin!
This plugin allows you to browse ADRs associated with your entities as well as a way to discover ADRs across others entities via Backstage Search. Use this to learn from the past experience of other projects to guide your own architecture decisions.
![ADR tab](./docs/adr-tab.png)
## Setup
1. Install this plugin:
plugins/adr/api-report.md
+3
View File
@@ -51,6 +51,9 @@ export type AdrFileInfo = {
type: string;
path: string;
name: string;
title?: string;
status?: string;
date?: string;
};
// @public
plugins/adr/docs/adr-tab.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 756 KiB

plugins/adr/src/api/types.ts
+9
View File
@@ -30,6 +30,15 @@ export type AdrFileInfo = {
/** The name of the ADR file. */
name: string;
/** The title of the ADR. */
title?: string;
/** The status of the ADR. */
status?: string;
/** The date of the ADR. */
date?: string;
};
/**
plugins/adr/src/components/EntityAdrContent/EntityAdrContent.tsx
+33 -8
View File
@@ -35,6 +35,7 @@ import {
} from '@backstage/plugin-adr-common';
import { useEntity } from '@backstage/plugin-catalog-react';
import {
Chip,
Grid,
List,
ListItem,
@@ -67,7 +68,9 @@ export const EntityAdrContent = (props: {
const classes = useStyles();
const { entity } = useEntity();
const rootLink = useRouteRef(rootRouteRef);
const [adrList, setAdrList] = useState<string[]>([]);
const [adrList, setAdrList] = useState<
{ name: string; title?: string; status?: string; date?: string }[]
>([]);
const [searchParams, setSearchParams] = useSearchParams();
const scmIntegrations = useApi(scmIntegrationsApiRef);
const adrApi = useApi(adrApiRef);
@@ -79,10 +82,10 @@ export const EntityAdrContent = (props: {
}, [entity, scmIntegrations]);
const selectedAdr =
adrList.find(adr => adr === searchParams.get('record')) ?? '';
adrList.find(adr => adr.name === searchParams.get('record'))?.name ?? '';
useEffect(() => {
if (adrList.length && !selectedAdr) {
searchParams.set('record', adrList[0]);
searchParams.set('record', adrList[0].name);
setSearchParams(searchParams, { replace: true });
}
});
@@ -100,11 +103,22 @@ export const EntityAdrContent = (props: {
? filePathFilterFn(item.name)
: madrFilePathFilter(item.name)),
)
.map(({ name }: { name: string }) => name);
.map(({ name, title, status, date }) => ({ name, title, status, date }));
setAdrList(adrs);
}, [filePathFilterFn, value]);
const getChipColor = (status: string) => {
switch (status) {
case 'accepted':
return 'primary';
case 'rejected' || 'deprecated':
return 'secondary';
default:
return 'default';
}
};
return (
<Content>
<ContentHeader title="Architecture Decision Records">
@@ -133,13 +147,24 @@ export const EntityAdrContent = (props: {
key={idx}
button
component={Link}
to={`${rootLink()}?record=${adr}`}
selected={selectedAdr === adr}
to={`${rootLink()}?record=${adr.name}`}
selected={selectedAdr === adr.name}
>
<ListItemText
secondaryTypographyProps={{ noWrap: true }}
secondary={adr.replace(/\.md$/, '')}
primaryTypographyProps={{
style: { whiteSpace: 'normal' },
}}
primary={adr.title ?? adr?.name.replace(/\.md$/, '')}
secondary={adr.date}
/>
{adr.status && (
<Chip
label={adr.status}
size="small"
variant="outlined"
color={getChipColor(adr.status)}
/>
)}
</ListItem>
))}
</List>