@backstage/plugin-techdocs-node 1.12.12-next.1 → 1.12.12

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @backstage/plugin-techdocs-node
 
+## 1.12.12
+
+### Patch Changes
+
+- 7774828: Updated dependency `@smithy/node-http-handler` to `^3.0.0`.
+- 720a2f9: Updated dependency `git-url-parse` to `^15.0.0`.
+- fbdc631: Allow to pass StorageOptions to GCS Publisher
+- Updated dependencies
+  - @backstage/integration@1.15.1
+  - @backstage/backend-plugin-api@1.0.1
+  - @backstage/catalog-model@1.7.0
+  - @backstage/config@1.2.0
+  - @backstage/errors@1.2.4
+  - @backstage/integration-aws-node@0.1.12
+  - @backstage/plugin-search-common@1.2.14
+  - @backstage/plugin-techdocs-common@0.1.0
+
+## 1.12.12-next.2
+
+### Patch Changes
+
+- 7774828: Updated dependency `@smithy/node-http-handler` to `^3.0.0`.
+- 720a2f9: Updated dependency `git-url-parse` to `^15.0.0`.
+- fbdc631: Allow to pass StorageOptions to GCS Publisher
+- Updated dependencies
+  - @backstage/integration@1.15.1-next.1
+  - @backstage/backend-plugin-api@1.0.1-next.1
+  - @backstage/catalog-model@1.7.0
+  - @backstage/config@1.2.0
+  - @backstage/errors@1.2.4
+  - @backstage/integration-aws-node@0.1.12
+  - @backstage/plugin-search-common@1.2.14
+  - @backstage/plugin-techdocs-common@0.1.0
+
 ## 1.12.12-next.1
 
 ### Patch Changes

package/dist/extensions.cjs.js

@@ -0,0 +1,22 @@
+'use strict';
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+
+const techdocsBuildsExtensionPoint = backendPluginApi.createExtensionPoint({
+  id: "techdocs.builds"
+});
+const techdocsGeneratorExtensionPoint = backendPluginApi.createExtensionPoint({
+  id: "techdocs.generator"
+});
+const techdocsPreparerExtensionPoint = backendPluginApi.createExtensionPoint({
+  id: "techdocs.preparer"
+});
+const techdocsPublisherExtensionPoint = backendPluginApi.createExtensionPoint({
+  id: "techdocs.publisher"
+});
+
+exports.techdocsBuildsExtensionPoint = techdocsBuildsExtensionPoint;
+exports.techdocsGeneratorExtensionPoint = techdocsGeneratorExtensionPoint;
+exports.techdocsPreparerExtensionPoint = techdocsPreparerExtensionPoint;
+exports.techdocsPublisherExtensionPoint = techdocsPublisherExtensionPoint;
+//# sourceMappingURL=extensions.cjs.js.map

package/dist/extensions.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.cjs.js","sources":["../src/extensions.ts"],"sourcesContent":["/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { createExtensionPoint } from '@backstage/backend-plugin-api';\nimport { DocsBuildStrategy } from './techdocsTypes';\nimport {\n  PreparerBase,\n  PublisherBase,\n  PublisherType,\n  RemoteProtocol,\n  TechdocsGenerator,\n} from './stages';\nimport * as winston from 'winston';\nimport { PublisherSettings } from './stages/publish/types';\n\n/**\n * Extension point type for configuring TechDocs builds.\n *\n * @public\n */\nexport interface TechdocsBuildsExtensionPoint {\n  setBuildStrategy(buildStrategy: DocsBuildStrategy): void;\n  setBuildLogTransport(transport: winston.transport): void;\n}\n\n/**\n * Extension point for configuring TechDocs builds.\n *\n * @public\n */\nexport const techdocsBuildsExtensionPoint =\n  createExtensionPoint<TechdocsBuildsExtensionPoint>({\n    id: 'techdocs.builds',\n  });\n\n/**\n * Extension point type for configuring a custom TechDocs generator\n *\n * @public\n */\nexport interface TechdocsGeneratorExtensionPoint {\n  setTechdocsGenerator(generator: TechdocsGenerator): void;\n}\n\n/**\n * Extension point for configuring a custom TechDocs generator\n *\n * @public\n */\nexport const techdocsGeneratorExtensionPoint =\n  createExtensionPoint<TechdocsGeneratorExtensionPoint>({\n    id: 'techdocs.generator',\n  });\n\n/**\n * Extension point type for configuring a custom TechDocs preparer\n *\n * @public\n */\nexport interface TechdocsPreparerExtensionPoint {\n  registerPreparer(protocol: RemoteProtocol, preparer: PreparerBase): void;\n}\n\n/**\n * Extension point for configuring a custom TechDocs preparer\n *\n * @public\n */\nexport const techdocsPreparerExtensionPoint =\n  createExtensionPoint<TechdocsPreparerExtensionPoint>({\n    id: 'techdocs.preparer',\n  });\n\n/**\n * Extension point type for configuring a custom TechDocs publisher\n *\n * @public\n */\nexport interface TechdocsPublisherExtensionPoint {\n  registerPublisher(type: PublisherType, publisher: PublisherBase): void;\n  registerPublisherSettings<T extends keyof PublisherSettings>(\n    publisher: T,\n    settings: PublisherSettings[T],\n  ): void;\n}\n\n/**\n * Extension point for configuring a custom TechDocs publisher\n *\n * @public\n */\nexport const techdocsPublisherExtensionPoint =\n  createExtensionPoint<TechdocsPublisherExtensionPoint>({\n    id: 'techdocs.publisher',\n  });\n"],"names":["createExtensionPoint"],"mappings":";;;;AA0CO,MAAM,+BACXA,qCAAmD,CAAA;AAAA,EACjD,EAAI,EAAA,iBAAA;AACN,CAAC,EAAA;AAgBI,MAAM,kCACXA,qCAAsD,CAAA;AAAA,EACpD,EAAI,EAAA,oBAAA;AACN,CAAC,EAAA;AAgBI,MAAM,iCACXA,qCAAqD,CAAA;AAAA,EACnD,EAAI,EAAA,mBAAA;AACN,CAAC,EAAA;AAoBI,MAAM,kCACXA,qCAAsD,CAAA;AAAA,EACpD,EAAI,EAAA,oBAAA;AACN,CAAC;;;;;;;"}

package/dist/helpers.cjs.js

@@ -0,0 +1,80 @@
+'use strict';
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+var catalogModel = require('@backstage/catalog-model');
+var errors = require('@backstage/errors');
+var pluginTechdocsCommon = require('@backstage/plugin-techdocs-common');
+var path = require('path');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var path__default = /*#__PURE__*/_interopDefaultCompat(path);
+
+const parseReferenceAnnotation = (annotationName, entity) => {
+  const annotation = entity.metadata.annotations?.[annotationName];
+  if (!annotation) {
+    throw new errors.InputError(
+      `No location annotation provided in entity: ${entity.metadata.name}`
+    );
+  }
+  const { type, target } = catalogModel.parseLocationRef(annotation);
+  return {
+    type,
+    target
+  };
+};
+const transformDirLocation = (entity, dirAnnotation, scmIntegrations) => {
+  const location = catalogModel.getEntitySourceLocation(entity);
+  switch (location.type) {
+    case "url": {
+      const target = scmIntegrations.resolveUrl({
+        url: dirAnnotation.target,
+        base: location.target
+      });
+      return {
+        type: "url",
+        target
+      };
+    }
+    case "file": {
+      const target = backendPluginApi.resolveSafeChildPath(
+        path__default.default.dirname(location.target),
+        dirAnnotation.target
+      );
+      return {
+        type: "dir",
+        target
+      };
+    }
+    default:
+      throw new errors.InputError(`Unable to resolve location type ${location.type}`);
+  }
+};
+const getLocationForEntity = (entity, scmIntegration) => {
+  const annotation = parseReferenceAnnotation(pluginTechdocsCommon.TECHDOCS_ANNOTATION, entity);
+  switch (annotation.type) {
+    case "url":
+      return annotation;
+    case "dir":
+      return transformDirLocation(entity, annotation, scmIntegration);
+    default:
+      throw new Error(`Invalid reference annotation ${annotation.type}`);
+  }
+};
+const getDocFilesFromRepository = async (reader, entity, opts) => {
+  const { target } = parseReferenceAnnotation(pluginTechdocsCommon.TECHDOCS_ANNOTATION, entity);
+  opts?.logger?.debug(`Reading files from ${target}`);
+  const readTreeResponse = await reader.readTree(target, { etag: opts?.etag });
+  const preparedDir = await readTreeResponse.dir();
+  opts?.logger?.debug(`Tree downloaded and stored at ${preparedDir}`);
+  return {
+    preparedDir,
+    etag: readTreeResponse.etag
+  };
+};
+
+exports.getDocFilesFromRepository = getDocFilesFromRepository;
+exports.getLocationForEntity = getLocationForEntity;
+exports.parseReferenceAnnotation = parseReferenceAnnotation;
+exports.transformDirLocation = transformDirLocation;
+//# sourceMappingURL=helpers.cjs.js.map

package/dist/helpers.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.cjs.js","sources":["../src/helpers.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  LoggerService,\n  UrlReaderService,\n  resolveSafeChildPath,\n} from '@backstage/backend-plugin-api';\nimport {\n  Entity,\n  getEntitySourceLocation,\n  parseLocationRef,\n} from '@backstage/catalog-model';\nimport { InputError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common';\nimport path from 'path';\nimport { PreparerResponse, RemoteProtocol } from './stages/prepare/types';\n\n/**\n * Parsed location annotation\n * @public\n */\nexport type ParsedLocationAnnotation = {\n  type: RemoteProtocol;\n  target: string;\n};\n\n/**\n * Returns a parsed locations annotation\n * @public\n * @param annotationName - The name of the annotation in the entity metadata\n * @param entity - A TechDocs entity instance\n */\nexport const parseReferenceAnnotation = (\n  annotationName: string,\n  entity: Entity,\n): ParsedLocationAnnotation => {\n  const annotation = entity.metadata.annotations?.[annotationName];\n  if (!annotation) {\n    throw new InputError(\n      `No location annotation provided in entity: ${entity.metadata.name}`,\n    );\n  }\n\n  const { type, target } = parseLocationRef(annotation);\n  return {\n    type: type as RemoteProtocol,\n    target,\n  };\n};\n\n/**\n * TechDocs references of type `dir` are relative the source location of the entity.\n * This function transforms relative references to absolute ones, based on the\n * location the entity was ingested from. If the entity was registered by a `url`\n * location, it returns a `url` location with a resolved target that points to the\n * targeted subfolder. If the entity was registered by a `file` location, it returns\n * an absolute `dir` location.\n * @public\n * @param entity - the entity with annotations\n * @param dirAnnotation - the parsed techdocs-ref annotation of type 'dir'\n * @param scmIntegrations - access to the scmIntegration to do url transformations\n * @throws if the entity doesn't specify a `dir` location or is ingested from an unsupported location.\n * @returns the transformed location with an absolute target.\n */\nexport const transformDirLocation = (\n  entity: Entity,\n  dirAnnotation: ParsedLocationAnnotation,\n  scmIntegrations: ScmIntegrationRegistry,\n): { type: 'dir' | 'url'; target: string } => {\n  const location = getEntitySourceLocation(entity);\n\n  switch (location.type) {\n    case 'url': {\n      const target = scmIntegrations.resolveUrl({\n        url: dirAnnotation.target,\n        base: location.target,\n      });\n\n      return {\n        type: 'url',\n        target,\n      };\n    }\n\n    case 'file': {\n      // only permit targets in the same folder as the target of the `file` location!\n      const target = resolveSafeChildPath(\n        path.dirname(location.target),\n        dirAnnotation.target,\n      );\n\n      return {\n        type: 'dir',\n        target,\n      };\n    }\n\n    default:\n      throw new InputError(`Unable to resolve location type ${location.type}`);\n  }\n};\n\n/**\n * Returns an entity reference based on the TechDocs annotation type\n * @public\n * @param entity - A TechDocs instance\n * @param scmIntegration - An implementation for  SCM integration API\n */\nexport const getLocationForEntity = (\n  entity: Entity,\n  scmIntegration: ScmIntegrationRegistry,\n): ParsedLocationAnnotation => {\n  const annotation = parseReferenceAnnotation(TECHDOCS_ANNOTATION, entity);\n\n  switch (annotation.type) {\n    case 'url':\n      return annotation;\n    case 'dir':\n      return transformDirLocation(entity, annotation, scmIntegration);\n    default:\n      throw new Error(`Invalid reference annotation ${annotation.type}`);\n  }\n};\n\n/**\n * Returns a preparer response {@link PreparerResponse}\n * @public\n * @param reader - Read a tree of files from a repository\n * @param entity - A TechDocs entity instance\n * @param opts - Options for configuring the reader, e.g. logger, etag, etc.\n */\nexport const getDocFilesFromRepository = async (\n  reader: UrlReaderService,\n  entity: Entity,\n  opts?: { etag?: string; logger?: LoggerService },\n): Promise<PreparerResponse> => {\n  const { target } = parseReferenceAnnotation(TECHDOCS_ANNOTATION, entity);\n\n  opts?.logger?.debug(`Reading files from ${target}`);\n  // readTree will throw NotModifiedError if etag has not changed.\n  const readTreeResponse = await reader.readTree(target, { etag: opts?.etag });\n  const preparedDir = await readTreeResponse.dir();\n\n  opts?.logger?.debug(`Tree downloaded and stored at ${preparedDir}`);\n\n  return {\n    preparedDir,\n    etag: readTreeResponse.etag,\n  };\n};\n"],"names":["InputError","parseLocationRef","getEntitySourceLocation","resolveSafeChildPath","path","TECHDOCS_ANNOTATION"],"mappings":";;;;;;;;;;;;AA+Ca,MAAA,wBAAA,GAA2B,CACtC,cAAA,EACA,MAC6B,KAAA;AAC7B,EAAA,MAAM,UAAa,GAAA,MAAA,CAAO,QAAS,CAAA,WAAA,GAAc,cAAc,CAAA,CAAA;AAC/D,EAAA,IAAI,CAAC,UAAY,EAAA;AACf,IAAA,MAAM,IAAIA,iBAAA;AAAA,MACR,CAAA,2CAAA,EAA8C,MAAO,CAAA,QAAA,CAAS,IAAI,CAAA,CAAA;AAAA,KACpE,CAAA;AAAA,GACF;AAEA,EAAA,MAAM,EAAE,IAAA,EAAM,MAAO,EAAA,GAAIC,8BAAiB,UAAU,CAAA,CAAA;AACpD,EAAO,OAAA;AAAA,IACL,IAAA;AAAA,IACA,MAAA;AAAA,GACF,CAAA;AACF,EAAA;AAgBO,MAAM,oBAAuB,GAAA,CAClC,MACA,EAAA,aAAA,EACA,eAC4C,KAAA;AAC5C,EAAM,MAAA,QAAA,GAAWC,qCAAwB,MAAM,CAAA,CAAA;AAE/C,EAAA,QAAQ,SAAS,IAAM;AAAA,IACrB,KAAK,KAAO,EAAA;AACV,MAAM,MAAA,MAAA,GAAS,gBAAgB,UAAW,CAAA;AAAA,QACxC,KAAK,aAAc,CAAA,MAAA;AAAA,QACnB,MAAM,QAAS,CAAA,MAAA;AAAA,OAChB,CAAA,CAAA;AAED,MAAO,OAAA;AAAA,QACL,IAAM,EAAA,KAAA;AAAA,QACN,MAAA;AAAA,OACF,CAAA;AAAA,KACF;AAAA,IAEA,KAAK,MAAQ,EAAA;AAEX,MAAA,MAAM,MAAS,GAAAC,qCAAA;AAAA,QACbC,qBAAA,CAAK,OAAQ,CAAA,QAAA,CAAS,MAAM,CAAA;AAAA,QAC5B,aAAc,CAAA,MAAA;AAAA,OAChB,CAAA;AAEA,MAAO,OAAA;AAAA,QACL,IAAM,EAAA,KAAA;AAAA,QACN,MAAA;AAAA,OACF,CAAA;AAAA,KACF;AAAA,IAEA;AACE,MAAA,MAAM,IAAIJ,iBAAA,CAAW,CAAmC,gCAAA,EAAA,QAAA,CAAS,IAAI,CAAE,CAAA,CAAA,CAAA;AAAA,GAC3E;AACF,EAAA;AAQa,MAAA,oBAAA,GAAuB,CAClC,MAAA,EACA,cAC6B,KAAA;AAC7B,EAAM,MAAA,UAAA,GAAa,wBAAyB,CAAAK,wCAAA,EAAqB,MAAM,CAAA,CAAA;AAEvE,EAAA,QAAQ,WAAW,IAAM;AAAA,IACvB,KAAK,KAAA;AACH,MAAO,OAAA,UAAA,CAAA;AAAA,IACT,KAAK,KAAA;AACH,MAAO,OAAA,oBAAA,CAAqB,MAAQ,EAAA,UAAA,EAAY,cAAc,CAAA,CAAA;AAAA,IAChE;AACE,MAAA,MAAM,IAAI,KAAA,CAAM,CAAgC,6BAAA,EAAA,UAAA,CAAW,IAAI,CAAE,CAAA,CAAA,CAAA;AAAA,GACrE;AACF,EAAA;AASO,MAAM,yBAA4B,GAAA,OACvC,MACA,EAAA,MAAA,EACA,IAC8B,KAAA;AAC9B,EAAA,MAAM,EAAE,MAAA,EAAW,GAAA,wBAAA,CAAyBA,0CAAqB,MAAM,CAAA,CAAA;AAEvE,EAAA,IAAA,EAAM,MAAQ,EAAA,KAAA,CAAM,CAAsB,mBAAA,EAAA,MAAM,CAAE,CAAA,CAAA,CAAA;AAElD,EAAM,MAAA,gBAAA,GAAmB,MAAM,MAAO,CAAA,QAAA,CAAS,QAAQ,EAAE,IAAA,EAAM,IAAM,EAAA,IAAA,EAAM,CAAA,CAAA;AAC3E,EAAM,MAAA,WAAA,GAAc,MAAM,gBAAA,CAAiB,GAAI,EAAA,CAAA;AAE/C,EAAA,IAAA,EAAM,MAAQ,EAAA,KAAA,CAAM,CAAiC,8BAAA,EAAA,WAAW,CAAE,CAAA,CAAA,CAAA;AAElE,EAAO,OAAA;AAAA,IACL,WAAA;AAAA,IACA,MAAM,gBAAiB,CAAA,IAAA;AAAA,GACzB,CAAA;AACF;;;;;;;"}