From 69bd94040808db493e3be77d5daf717dfbaa8b5d Mon Sep 17 00:00:00 2001 From: MT Lewis Date: Wed, 24 Jul 2024 18:03:55 +0100 Subject: [PATCH] techdocs: switch to using constants from techdocs-common for annotations Signed-off-by: MT Lewis --- .changeset/eighty-emus-leave.md | 7 +++++ plugins/techdocs-backend/package.json | 1 + .../search/DefaultTechDocsCollator.test.ts | 3 +- .../src/search/DefaultTechDocsCollator.ts | 3 +- plugins/techdocs-node/package.json | 1 + plugins/techdocs-node/src/helpers.test.ts | 29 ++++++++++--------- plugins/techdocs-node/src/helpers.ts | 11 ++----- .../src/stages/prepare/dir.test.ts | 7 +++-- .../techdocs-node/src/stages/prepare/dir.ts | 6 ++-- .../src/stages/prepare/preparers.ts | 6 ++-- plugins/techdocs/package.json | 1 + plugins/techdocs/src/EntityPageDocs.tsx | 3 +- plugins/techdocs/src/Router.tsx | 8 ++--- .../home/components/TechDocsCustomHome.tsx | 5 ++-- .../src/home/components/TechDocsPicker.tsx | 3 +- yarn.lock | 11 +++++++ 16 files changed, 61 insertions(+), 44 deletions(-) create mode 100644 .changeset/eighty-emus-leave.md diff --git a/.changeset/eighty-emus-leave.md b/.changeset/eighty-emus-leave.md new file mode 100644 index 0000000000..8e02c7cf94 --- /dev/null +++ b/.changeset/eighty-emus-leave.md @@ -0,0 +1,7 @@ +--- +'@backstage/plugin-techdocs-backend': patch +'@backstage/plugin-techdocs-node': patch +'@backstage/plugin-techdocs': patch +--- + +Use annotation constants from new techdocs-common package. diff --git a/plugins/techdocs-backend/package.json b/plugins/techdocs-backend/package.json index fc862ad909..2b4f23b342 100644 --- a/plugins/techdocs-backend/package.json +++ b/plugins/techdocs-backend/package.json @@ -68,6 +68,7 @@ "@backstage/plugin-catalog-common": "workspace:^", "@backstage/plugin-permission-common": "workspace:^", "@backstage/plugin-search-backend-module-techdocs": "workspace:^", + "@backstage/plugin-techdocs-common": "workspace:^", "@backstage/plugin-techdocs-node": "workspace:^", "@types/express": "^4.17.6", "express": "^4.17.1", diff --git a/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.test.ts b/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.test.ts index 64b0917202..96f8cfd696 100644 --- a/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.test.ts +++ b/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.test.ts @@ -28,6 +28,7 @@ import { import { setupServer } from 'msw/node'; import { rest } from 'msw'; import { ConfigReader } from '@backstage/config'; +import { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common'; const logger = loggerToWinstonLogger(mockServices.logger.mock()); @@ -66,7 +67,7 @@ const expectedEntities: Entity[] = [ name: 'test-entity-with-docs', description: 'Documented description', annotations: { - 'backstage.io/techdocs-ref': './', + [TECHDOCS_ANNOTATION]: './', }, }, spec: { diff --git a/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.ts b/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.ts index b683127172..527846df79 100644 --- a/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.ts +++ b/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.ts @@ -37,6 +37,7 @@ import { CATALOG_FILTER_EXISTS, } from '@backstage/catalog-client'; import { TechDocsDocument } from '@backstage/plugin-techdocs-node'; +import { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common'; interface MkSearchIndexDoc { title: string; @@ -107,7 +108,7 @@ export class DefaultTechDocsCollator { ).getEntities( { filter: { - 'metadata.annotations.backstage.io/techdocs-ref': + [`metadata.annotations.${TECHDOCS_ANNOTATION}`]: CATALOG_FILTER_EXISTS, }, fields: [ diff --git a/plugins/techdocs-node/package.json b/plugins/techdocs-node/package.json index 94711e8933..16cf0d9155 100644 --- a/plugins/techdocs-node/package.json +++ b/plugins/techdocs-node/package.json @@ -61,6 +61,7 @@ "@backstage/integration": "workspace:^", "@backstage/integration-aws-node": "workspace:^", "@backstage/plugin-search-common": "workspace:^", + "@backstage/plugin-techdocs-common": "workspace:^", "@google-cloud/storage": "^7.0.0", "@smithy/node-http-handler": "^2.1.7", "@trendyol-js/openstack-swift-sdk": "^0.0.7", diff --git a/plugins/techdocs-node/src/helpers.test.ts b/plugins/techdocs-node/src/helpers.test.ts index 1b25abded3..4f77a5432b 100644 --- a/plugins/techdocs-node/src/helpers.test.ts +++ b/plugins/techdocs-node/src/helpers.test.ts @@ -27,6 +27,7 @@ import { ScmIntegrations } from '@backstage/integration'; import os from 'os'; import path from 'path'; import { Readable } from 'stream'; +import { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common'; import { getDocFilesFromRepository, getLocationForEntity, @@ -64,7 +65,7 @@ const metadataBase = { const goodAnnotation = { annotations: { - 'backstage.io/techdocs-ref': + [TECHDOCS_ANNOTATION]: 'url:https://github.com/backstage/backstage/blob/master/subfolder/', }, }; @@ -81,7 +82,7 @@ const mockEntityWithAnnotation: Entity = { const badAnnotation = { annotations: { - 'backstage.io/techdocs-ref': 'bad-annotation', + [TECHDOCS_ANNOTATION]: 'bad-annotation', }, }; @@ -102,7 +103,7 @@ afterEach(() => jest.resetAllMocks()); describe('parseReferenceAnnotation', () => { it('should parse annotation', () => { const parsedLocationAnnotation = parseReferenceAnnotation( - 'backstage.io/techdocs-ref', + TECHDOCS_ANNOTATION, mockEntityWithAnnotation, ); expect(parsedLocationAnnotation.type).toBe('url'); @@ -113,14 +114,14 @@ describe('parseReferenceAnnotation', () => { it('should throw error without annotation', () => { expect(() => { - parseReferenceAnnotation('backstage.io/techdocs-ref', entityBase); + parseReferenceAnnotation(TECHDOCS_ANNOTATION, entityBase); }).toThrow(/No location annotation/); }); it('should throw error with bad annotation', () => { expect(() => { parseReferenceAnnotation( - 'backstage.io/techdocs-ref', + TECHDOCS_ANNOTATION, mockEntityWithBadAnnotation, ); }).toThrow(/Unable to parse/); @@ -146,14 +147,14 @@ describe('transformDirLocation', () => { metadata: { name: 'test', annotations: { - 'backstage.io/techdocs-ref': techdocsRef, + [TECHDOCS_ANNOTATION]: techdocsRef, }, }, }; const result = transformDirLocation( entity, - parseReferenceAnnotation('backstage.io/techdocs-ref', entity), + parseReferenceAnnotation(TECHDOCS_ANNOTATION, entity), scmIntegrations, ); @@ -179,14 +180,14 @@ describe('transformDirLocation', () => { metadata: { name: 'test', annotations: { - 'backstage.io/techdocs-ref': techdocsRef, + [TECHDOCS_ANNOTATION]: techdocsRef, }, }, }; const result = transformDirLocation( entity, - parseReferenceAnnotation('backstage.io/techdocs-ref', entity), + parseReferenceAnnotation(TECHDOCS_ANNOTATION, entity), scmIntegrations, ); @@ -206,7 +207,7 @@ describe('transformDirLocation', () => { metadata: { name: 'test', annotations: { - 'backstage.io/techdocs-ref': 'dir:..', + [TECHDOCS_ANNOTATION]: 'dir:..', }, }, }; @@ -214,7 +215,7 @@ describe('transformDirLocation', () => { expect(() => transformDirLocation( entity, - parseReferenceAnnotation('backstage.io/techdocs-ref', entity), + parseReferenceAnnotation(TECHDOCS_ANNOTATION, entity), scmIntegrations, ), ).toThrow( @@ -234,7 +235,7 @@ describe('transformDirLocation', () => { metadata: { name: 'test', annotations: { - 'backstage.io/techdocs-ref': 'dir:.', + [TECHDOCS_ANNOTATION]: 'dir:.', }, }, }; @@ -242,7 +243,7 @@ describe('transformDirLocation', () => { expect(() => transformDirLocation( entity, - parseReferenceAnnotation('backstage.io/techdocs-ref', entity), + parseReferenceAnnotation(TECHDOCS_ANNOTATION, entity), scmIntegrations, ), ).toThrow(/Unable to resolve location type other/); @@ -262,7 +263,7 @@ describe('getLocationForEntity', () => { metadata: { name: 'test', annotations: { - 'backstage.io/techdocs-ref': 'dir:.', + [TECHDOCS_ANNOTATION]: 'dir:.', }, }, }; diff --git a/plugins/techdocs-node/src/helpers.ts b/plugins/techdocs-node/src/helpers.ts index c293d16896..d64c7fc289 100644 --- a/plugins/techdocs-node/src/helpers.ts +++ b/plugins/techdocs-node/src/helpers.ts @@ -23,6 +23,7 @@ import { } from '@backstage/catalog-model'; import { InputError } from '@backstage/errors'; import { ScmIntegrationRegistry } from '@backstage/integration'; +import { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common'; import path from 'path'; import { Logger } from 'winston'; import { PreparerResponse, RemoteProtocol } from './stages/prepare/types'; @@ -122,10 +123,7 @@ export const getLocationForEntity = ( entity: Entity, scmIntegration: ScmIntegrationRegistry, ): ParsedLocationAnnotation => { - const annotation = parseReferenceAnnotation( - 'backstage.io/techdocs-ref', - entity, - ); + const annotation = parseReferenceAnnotation(TECHDOCS_ANNOTATION, entity); switch (annotation.type) { case 'url': @@ -149,10 +147,7 @@ export const getDocFilesFromRepository = async ( entity: Entity, opts?: { etag?: string; logger?: Logger }, ): Promise => { - const { target } = parseReferenceAnnotation( - 'backstage.io/techdocs-ref', - entity, - ); + const { target } = parseReferenceAnnotation(TECHDOCS_ANNOTATION, entity); opts?.logger?.debug(`Reading files from ${target}`); // readTree will throw NotModifiedError if etag has not changed. diff --git a/plugins/techdocs-node/src/stages/prepare/dir.test.ts b/plugins/techdocs-node/src/stages/prepare/dir.test.ts index 5fbd56264e..a26c423aaf 100644 --- a/plugins/techdocs-node/src/stages/prepare/dir.test.ts +++ b/plugins/techdocs-node/src/stages/prepare/dir.test.ts @@ -14,6 +14,7 @@ * limitations under the License. */ import { UrlReader, loggerToWinstonLogger } from '@backstage/backend-common'; +import { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common'; import { ConfigReader } from '@backstage/config'; import { DirectoryPreparer } from './dir'; import { mockServices } from '@backstage/backend-test-utils'; @@ -61,7 +62,7 @@ describe('directory preparer', () => { const mockEntity = createMockEntity({ 'backstage.io/managed-by-location': 'file:/directory/documented-component.yaml', - 'backstage.io/techdocs-ref': 'dir:./our-documentation', + [TECHDOCS_ANNOTATION]: 'dir:./our-documentation', }); const { preparedDir } = await directoryPreparer.prepare(mockEntity); @@ -77,7 +78,7 @@ describe('directory preparer', () => { const mockEntity = createMockEntity({ 'backstage.io/managed-by-location': 'file:/directory/documented-component.yaml', - 'backstage.io/techdocs-ref': 'dir:/our-documentation/techdocs', + [TECHDOCS_ANNOTATION]: 'dir:/our-documentation/techdocs', }); await expect(directoryPreparer.prepare(mockEntity)).rejects.toThrow( @@ -94,7 +95,7 @@ describe('directory preparer', () => { const mockEntity = createMockEntity({ 'backstage.io/managed-by-location': 'does-not-exist:https://github.com/backstage/backstage/blob/master/catalog-info.yaml', - 'backstage.io/techdocs-ref': 'dir:./docs', + [TECHDOCS_ANNOTATION]: 'dir:./docs', }); await expect(directoryPreparer.prepare(mockEntity)).rejects.toThrow( diff --git a/plugins/techdocs-node/src/stages/prepare/dir.ts b/plugins/techdocs-node/src/stages/prepare/dir.ts index 6be9510a51..1c18b17a1e 100644 --- a/plugins/techdocs-node/src/stages/prepare/dir.ts +++ b/plugins/techdocs-node/src/stages/prepare/dir.ts @@ -22,6 +22,7 @@ import { ScmIntegrationRegistry, ScmIntegrations, } from '@backstage/integration'; +import { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common'; import { Logger } from 'winston'; import { parseReferenceAnnotation, transformDirLocation } from '../../helpers'; import { @@ -70,10 +71,7 @@ export class DirectoryPreparer implements PreparerBase { entity: Entity, options?: PreparerOptions, ): Promise { - const annotation = parseReferenceAnnotation( - 'backstage.io/techdocs-ref', - entity, - ); + const annotation = parseReferenceAnnotation(TECHDOCS_ANNOTATION, entity); const { type, target } = transformDirLocation( entity, annotation, diff --git a/plugins/techdocs-node/src/stages/prepare/preparers.ts b/plugins/techdocs-node/src/stages/prepare/preparers.ts index d0ba61bf40..f7df8b67f4 100644 --- a/plugins/techdocs-node/src/stages/prepare/preparers.ts +++ b/plugins/techdocs-node/src/stages/prepare/preparers.ts @@ -15,6 +15,7 @@ */ import { Entity } from '@backstage/catalog-model'; import { Config } from '@backstage/config'; +import { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common'; import { parseReferenceAnnotation } from '../../helpers'; import { DirectoryPreparer } from './dir'; import { UrlPreparer } from './url'; @@ -78,10 +79,7 @@ export class Preparers implements PreparerBuilder { * @returns */ get(entity: Entity): PreparerBase { - const { type } = parseReferenceAnnotation( - 'backstage.io/techdocs-ref', - entity, - ); + const { type } = parseReferenceAnnotation(TECHDOCS_ANNOTATION, entity); const preparer = this.preparerMap.get(type); if (!preparer) { diff --git a/plugins/techdocs/package.json b/plugins/techdocs/package.json index 2992c7a067..3558590938 100644 --- a/plugins/techdocs/package.json +++ b/plugins/techdocs/package.json @@ -72,6 +72,7 @@ "@backstage/plugin-catalog-react": "workspace:^", "@backstage/plugin-search-common": "workspace:^", "@backstage/plugin-search-react": "workspace:^", + "@backstage/plugin-techdocs-common": "workspace:^", "@backstage/plugin-techdocs-react": "workspace:^", "@backstage/theme": "workspace:^", "@material-ui/core": "^4.12.2", diff --git a/plugins/techdocs/src/EntityPageDocs.tsx b/plugins/techdocs/src/EntityPageDocs.tsx index af184bb1a8..07222190ae 100644 --- a/plugins/techdocs/src/EntityPageDocs.tsx +++ b/plugins/techdocs/src/EntityPageDocs.tsx @@ -19,14 +19,13 @@ import { getCompoundEntityRef, parseEntityRef, } from '@backstage/catalog-model'; +import { TECHDOCS_EXTERNAL_ANNOTATION } from '@backstage/plugin-techdocs-common'; import React from 'react'; import { TechDocsReaderPage } from './plugin'; import { TechDocsReaderPageContent } from './reader/components/TechDocsReaderPageContent'; import { TechDocsReaderPageSubheader } from './reader/components/TechDocsReaderPageSubheader'; -const TECHDOCS_EXTERNAL_ANNOTATION = 'backstage.io/techdocs-entity'; - type EntityPageDocsProps = { entity: Entity }; export const EntityPageDocs = ({ entity }: EntityPageDocsProps) => { diff --git a/plugins/techdocs/src/Router.tsx b/plugins/techdocs/src/Router.tsx index 719217a32d..87a53156d6 100644 --- a/plugins/techdocs/src/Router.tsx +++ b/plugins/techdocs/src/Router.tsx @@ -25,10 +25,10 @@ import { useEntity, MissingAnnotationEmptyState, } from '@backstage/plugin-catalog-react'; - -const TECHDOCS_ANNOTATION = 'backstage.io/techdocs-ref'; - -const TECHDOCS_EXTERNAL_ANNOTATION = 'backstage.io/techdocs-entity'; +import { + TECHDOCS_ANNOTATION, + TECHDOCS_EXTERNAL_ANNOTATION, +} from '@backstage/plugin-techdocs-common'; /** * Helper that takes in entity and returns true/false if TechDocs is available for the entity diff --git a/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx b/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx index 70bd946256..56d086acfc 100644 --- a/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx +++ b/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx @@ -39,6 +39,7 @@ import { ContentHeader, } from '@backstage/core-components'; import { useApi } from '@backstage/core-plugin-api'; +import { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common'; const panels = { DocsTable: DocsTable, @@ -153,7 +154,7 @@ export const TechDocsCustomHome = (props: TechDocsCustomHomeProps) => { } = useAsync(async () => { const response = await catalogApi.getEntities({ filter: { - 'metadata.annotations.backstage.io/techdocs-ref': CATALOG_FILTER_EXISTS, + [`metadata.annotations.${TECHDOCS_ANNOTATION}`]: CATALOG_FILTER_EXISTS, }, fields: [ 'apiVersion', @@ -165,7 +166,7 @@ export const TechDocsCustomHome = (props: TechDocsCustomHomeProps) => { ], }); return response.items.filter((entity: Entity) => { - return !!entity.metadata.annotations?.['backstage.io/techdocs-ref']; + return !!entity.metadata.annotations?.[TECHDOCS_ANNOTATION]; }); }); diff --git a/plugins/techdocs/src/home/components/TechDocsPicker.tsx b/plugins/techdocs/src/home/components/TechDocsPicker.tsx index 32c7b800eb..f7bd2430a1 100644 --- a/plugins/techdocs/src/home/components/TechDocsPicker.tsx +++ b/plugins/techdocs/src/home/components/TechDocsPicker.tsx @@ -21,11 +21,12 @@ import { EntityFilter, useEntityList, } from '@backstage/plugin-catalog-react'; +import { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common'; class TechDocsFilter implements EntityFilter { getCatalogFilters(): Record { return { - 'metadata.annotations.backstage.io/techdocs-ref': CATALOG_FILTER_EXISTS, + [`metadata.annotations.${TECHDOCS_ANNOTATION}`]: CATALOG_FILTER_EXISTS, }; } } diff --git a/yarn.lock b/yarn.lock index 8471404d21..a95a29be28 100644 --- a/yarn.lock +++ b/yarn.lock @@ -7740,6 +7740,7 @@ __metadata: "@backstage/plugin-catalog-common": "workspace:^" "@backstage/plugin-permission-common": "workspace:^" "@backstage/plugin-search-backend-module-techdocs": "workspace:^" + "@backstage/plugin-techdocs-common": "workspace:^" "@backstage/plugin-techdocs-node": "workspace:^" "@types/express": ^4.17.6 express: ^4.17.1 @@ -7755,6 +7756,14 @@ __metadata: languageName: unknown linkType: soft +"@backstage/plugin-techdocs-common@workspace:^, @backstage/plugin-techdocs-common@workspace:plugins/techdocs-common": + version: 0.0.0-use.local + resolution: "@backstage/plugin-techdocs-common@workspace:plugins/techdocs-common" + dependencies: + "@backstage/cli": "workspace:^" + languageName: unknown + linkType: soft + "@backstage/plugin-techdocs-module-addons-contrib@workspace:^, @backstage/plugin-techdocs-module-addons-contrib@workspace:plugins/techdocs-module-addons-contrib": version: 0.0.0-use.local resolution: "@backstage/plugin-techdocs-module-addons-contrib@workspace:plugins/techdocs-module-addons-contrib" @@ -7803,6 +7812,7 @@ __metadata: "@backstage/integration": "workspace:^" "@backstage/integration-aws-node": "workspace:^" "@backstage/plugin-search-common": "workspace:^" + "@backstage/plugin-techdocs-common": "workspace:^" "@google-cloud/storage": ^7.0.0 "@smithy/node-http-handler": ^2.1.7 "@trendyol-js/openstack-swift-sdk": ^0.0.7 @@ -7876,6 +7886,7 @@ __metadata: "@backstage/plugin-catalog-react": "workspace:^" "@backstage/plugin-search-common": "workspace:^" "@backstage/plugin-search-react": "workspace:^" + "@backstage/plugin-techdocs-common": "workspace:^" "@backstage/plugin-techdocs-module-addons-contrib": "workspace:^" "@backstage/plugin-techdocs-react": "workspace:^" "@backstage/test-utils": "workspace:^"