techdocs-common: Initialize package and move common code from techdocs-backend

packages/backend/package.json

@@ -31,6 +31,7 @@
     "@backstage/plugin-scaffolder-backend": "^0.3.2",
     "@backstage/plugin-sentry-backend": "^0.1.3",
     "@backstage/plugin-techdocs-backend": "^0.3.0",
+    "@backstage/techdocs-common": "^0.1.1",
     "@gitbeaker/node": "^25.2.0",
     "@octokit/rest": "^18.0.0",
     "azure-devops-node-api": "^10.1.1",

packages/backend/src/plugins/techdocs.ts

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
+import { createRouter } from '@backstage/plugin-techdocs-backend';
 import {
-  createRouter,
   DirectoryPreparer,
   Preparers,
   Generators,
@@ -23,7 +23,7 @@ import {
   CommonGitPreparer,
   UrlPreparer,
   Publisher,
-} from '@backstage/plugin-techdocs-backend';
+} from '@backstage/techdocs-common';
 import { PluginEnvironment } from '../types';
 import Docker from 'dockerode';
 

packages/techdocs-common/.eslintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: [require.resolve('@backstage/cli/config/eslint.backend')],
+};

packages/techdocs-common/README.md

@@ -0,0 +1,7 @@
+# @backstage/techdocs-common
+
+Common functionalities for TechDocs, to be shared between techdocs plugins and techdocs-cli
+
+## Usage
+
+TODO: List supported APIs

packages/techdocs-common/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@backstage/techdocs-common",
+  "description": "Common functionalities for TechDocs, to be shared between techdocs plugins and techdocs-cli",
+  "version": "0.1.1",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "packages/techdocs-common"
+  },
+  "keywords": [
+    "techdocs",
+    "backstage"
+  ],
+  "license": "Apache-2.0",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "backstage-cli build --outputs cjs,types",
+    "lint": "backstage-cli lint",
+    "test": "backstage-cli test",
+    "prepack": "backstage-cli prepack",
+    "postpack": "backstage-cli postpack",
+    "clean": "backstage-cli clean"
+  },
+  "bugs": {
+    "url": "https://github.com/backstage/backstage/issues"
+  },
+  "dependencies": {
+    "@backstage/backend-common": "^0.3.2",
+    "@backstage/catalog-model": "^0.3.1",
+    "@backstage/config": "^0.1.1",
+    "cross-fetch": "^3.0.6",
+    "dockerode": "^3.2.1",
+    "fs-extra": "^9.0.1",
+    "git-url-parse": "^11.4.0",
+    "js-yaml": "^3.14.0",
+    "mock-fs": "^4.13.0",
+    "nodegit": "^0.27.0",
+    "@types/dockerode": "^2.5.34",
+    "winston": "^3.2.1"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.3.1"
+  }
+}

packages/techdocs-common/src/helpers.ts

@@ -23,7 +23,7 @@ import { getDefaultBranch } from './default-branch';
 import { getGitRepoType, getTokenForGitRepo } from './git-auth';
 import { Entity } from '@backstage/catalog-model';
 import { InputError, UrlReader } from '@backstage/backend-common';
-import { RemoteProtocol } from './techdocs/stages/prepare/types';
+import { RemoteProtocol } from './stages/prepare/types';
 import { Logger } from 'winston';
 
 // Enables core.longpaths on windows to prevent crashing when checking out repos with long foldernames and/or deep nesting

packages/techdocs-common/src/index.ts

@@ -14,3 +14,6 @@
  * limitations under the License.
  */
 export * from './stages';
+export * from './helpers';
+export * from './default-branch';
+export * from './git-auth';

packages/techdocs-common/src/stages/generate/generators.test.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { Generators, TechdocsGenerator } from './';
+import { Generators, TechdocsGenerator } from '.';
 import { getVoidLogger } from '@backstage/backend-common';
 import { ConfigReader } from '@backstage/config';
 

packages/techdocs-common/src/stages/generate/helpers.test.ts

@@ -28,7 +28,7 @@ import {
   patchMkdocsYmlPreBuild,
 } from './helpers';
 import { RemoteProtocol } from '../prepare/types';
-import { ParsedLocationAnnotation } from '../../../helpers';
+import { ParsedLocationAnnotation } from '../../helpers';
 
 const mockEntity = {
   apiVersion: 'version',

packages/techdocs-common/src/stages/generate/helpers.ts

@@ -22,7 +22,7 @@ import yaml from 'js-yaml';
 import { Logger } from 'winston';
 import { Entity } from '@backstage/catalog-model';
 import { SupportedGeneratorKey } from './types';
-import { ParsedLocationAnnotation } from '../../../helpers';
+import { ParsedLocationAnnotation } from '../../helpers';
 import { RemoteProtocol } from '../prepare/types';
 
 // TODO: Implement proper support for more generators.

packages/techdocs-common/src/stages/generate/types.ts

@@ -16,7 +16,7 @@
 import { Writable } from 'stream';
 import Docker from 'dockerode';
 import { Entity } from '@backstage/catalog-model';
-import { ParsedLocationAnnotation } from '../../../helpers';
+import { ParsedLocationAnnotation } from '../../helpers';
 
 /**
  * The returned directory from the generator which is ready

packages/techdocs-common/src/stages/prepare/commonGit.test.ts

@@ -16,7 +16,7 @@
 
 import { getVoidLogger } from '@backstage/backend-common';
 import { CommonGitPreparer } from './commonGit';
-import { checkoutGitRepository } from '../../../helpers';
+import { checkoutGitRepository } from '../../helpers';
 
 function normalizePath(path: string) {
   return path
@@ -25,8 +25,8 @@ function normalizePath(path: string) {
     .join('/');
 }
 
-jest.mock('../../../helpers', () => ({
-  ...jest.requireActual<{}>('../../../helpers'),
+jest.mock('../../helpers', () => ({
+  ...jest.requireActual<{}>('../../helpers'),
   checkoutGitRepository: jest.fn(() => '/tmp/backstage-repo/org/name/branch'),
 }));
 

packages/techdocs-common/src/stages/prepare/commonGit.ts

@@ -17,10 +17,7 @@ import path from 'path';
 import { Entity } from '@backstage/catalog-model';
 import { PreparerBase } from './types';
 import parseGitUrl from 'git-url-parse';
-import {
-  parseReferenceAnnotation,
-  checkoutGitRepository,
-} from '../../../helpers';
+import { parseReferenceAnnotation, checkoutGitRepository } from '../../helpers';
 
 import { Logger } from 'winston';
 

packages/techdocs-common/src/stages/prepare/dir.test.ts

@@ -15,7 +15,7 @@
  */
 import { DirectoryPreparer } from './dir';
 import { getVoidLogger } from '@backstage/backend-common';
-import { checkoutGitRepository } from '../../../helpers';
+import { checkoutGitRepository } from '../../helpers';
 
 function normalizePath(path: string) {
   return path
@@ -24,8 +24,8 @@ function normalizePath(path: string) {
     .join('/');
 }
 
-jest.mock('../../../helpers', () => ({
-  ...jest.requireActual<{}>('../../../helpers'),
+jest.mock('../../helpers', () => ({
+  ...jest.requireActual<{}>('../../helpers'),
   checkoutGitRepository: jest.fn(() => '/tmp/backstage-repo/org/name/branch/'),
 }));
 

packages/techdocs-common/src/stages/prepare/dir.ts

@@ -16,10 +16,7 @@
 import { PreparerBase } from './types';
 import { Entity } from '@backstage/catalog-model';
 import path from 'path';
-import {
-  parseReferenceAnnotation,
-  checkoutGitRepository,
-} from '../../../helpers';
+import { parseReferenceAnnotation, checkoutGitRepository } from '../../helpers';
 import { InputError } from '@backstage/backend-common';
 import parseGitUrl from 'git-url-parse';
 import { Logger } from 'winston';

packages/techdocs-common/src/stages/prepare/preparers.ts

@@ -16,7 +16,7 @@
 
 import { PreparerBase, RemoteProtocol, PreparerBuilder } from './types';
 import { Entity } from '@backstage/catalog-model';
-import { parseReferenceAnnotation } from '../../../helpers';
+import { parseReferenceAnnotation } from '../../helpers';
 
 export class Preparers implements PreparerBuilder {
   private preparerMap = new Map<RemoteProtocol, PreparerBase>();

packages/techdocs-common/src/stages/prepare/url.ts

@@ -15,8 +15,7 @@
  */
 import { Entity } from '@backstage/catalog-model';
 import { PreparerBase } from './types';
-import { getDocFilesFromRepository } from '../../../helpers';
-
+import { getDocFilesFromRepository } from '../../helpers';
 import { Logger } from 'winston';
 import { UrlReader } from '@backstage/backend-common';
 

packages/techdocs-common/src/stages/publish/local.test.ts

@@ -58,12 +58,12 @@ describe('local publisher', () => {
     await publisher.publish({ entity: mockEntity, directory: tempDir });
     const publishDir = path.resolve(
       __dirname,
-      `../../../../static/docs/${mockEntity.metadata.name}`,
+      `../../../../../plugins/techdocs-backend/static/docs/${mockEntity.metadata.name}`,
     );
 
     const resultDir = path.resolve(
       __dirname,
-      `../../../../static/docs/default/${mockEntity.kind}/${mockEntity.metadata.name}`,
+      `../../../../../plugins/techdocs-backend/static/docs/default/${mockEntity.kind}/${mockEntity.metadata.name}`,
     );
 
     expect(fs.existsSync(resultDir)).toBeTruthy();

plugins/techdocs-backend/package.json

@@ -23,19 +23,14 @@
     "@backstage/backend-common": "^0.3.2",
     "@backstage/catalog-model": "^0.3.1",
     "@backstage/config": "^0.1.1",
+    "@backstage/techdocs-common": "^0.1.1",
     "@types/dockerode": "^2.5.34",
     "@types/express": "^4.17.6",
-    "command-exists-promise": "^2.0.2",
     "cross-fetch": "^3.0.6",
     "dockerode": "^3.2.1",
     "express": "^4.17.1",
     "express-promise-router": "^3.0.3",
-    "fs-extra": "^9.0.1",
-    "git-url-parse": "^11.4.0",
-    "js-yaml": "^3.14.0",
     "knex": "^0.21.6",
-    "mock-fs": "^4.13.0",
-    "nodegit": "^0.27.0",
     "winston": "^3.2.1"
   },
   "devDependencies": {

plugins/techdocs-backend/src/index.ts

@@ -15,4 +15,3 @@
  */
 
 export * from './service/router';
-export * from './techdocs';

plugins/techdocs-backend/src/service/helpers.ts

@@ -22,9 +22,10 @@ import {
   GeneratorBuilder,
   PreparerBase,
   GeneratorBase,
-} from '../techdocs';
+  getLocationForEntity,
+  getLastCommitTimestamp,
+} from '@backstage/techdocs-common';
 import { BuildMetadataStorage } from '../storage';
-import { getLocationForEntity, getLastCommitTimestamp } from '../helpers';
 
 const getEntityId = (entity: Entity) => {
   return `${entity.kind}:${entity.metadata.namespace ?? ''}:${

plugins/techdocs-backend/src/service/router.ts

@@ -20,14 +20,18 @@ import Knex from 'knex';
 import fetch from 'cross-fetch';
 import { Config } from '@backstage/config';
 import Docker from 'dockerode';
-import { GeneratorBuilder, PreparerBuilder, PublisherBase } from '../techdocs';
+import {
+  GeneratorBuilder,
+  PreparerBuilder,
+  PublisherBase,
+  getLocationForEntity,
+} from '@backstage/techdocs-common';
 import {
   PluginEndpointDiscovery,
   resolvePackagePath,
 } from '@backstage/backend-common';
 import { Entity } from '@backstage/catalog-model';
 import { DocsBuilder } from './helpers';
-import { getLocationForEntity } from '../helpers';
 
 type RouterOptions = {
   preparers: PreparerBuilder;

plugins/techdocs-backend/src/service/standaloneServer.ts

@@ -28,7 +28,7 @@ import {
   Generators,
   TechdocsGenerator,
   Publisher,
-} from '../techdocs';
+} from '@backstage/techdocs-common';
 import { ConfigReader } from '@backstage/config';
 
 export interface ServerOptions {

plugins/techdocs/package.json

@@ -25,6 +25,7 @@
     "@backstage/core": "^0.3.2",
     "@backstage/core-api": "^0.2.3",
     "@backstage/plugin-catalog": "^0.2.4",
+    "@backstage/techdocs-common": "^0.1.1",
     "@backstage/test-utils": "^0.1.3",
     "@backstage/theme": "^0.2.1",
     "@material-ui/core": "^4.11.0",