@evergreen-dev/backstage-plugin 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @evergreen-dev/backstage-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Backstage entity card that shows Evergreen lifecycle risk per Component. Also install `@evergreen-dev/backstage-plugin-backend`.
+
+Setup, configuration, and the CI export step: https://github.com/arminazimi/evergreen/tree/main/integrations/backstage#readme

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@evergreen-dev/backstage-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Backstage entity card that shows Evergreen lifecycle risk per component from the portal export.",
+  "keywords": [
+    "backstage",
+    "backstage-plugin",
+    "evergreen",
+    "end-of-life",
+    "lifecycle",
+    "deprecation"
+  ],
+  "homepage": "https://github.com/arminazimi/evergreen/tree/main/integrations/backstage#readme",
+  "bugs": {
+    "url": "https://github.com/arminazimi/evergreen/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arminazimi/evergreen.git",
+    "directory": "integrations/backstage/plugin"
+  },
+  "license": "Apache-2.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "backstage": {
+    "role": "frontend-plugin",
+    "pluginId": "evergreen",
+    "pluginPackages": [
+      "@evergreen-dev/backstage-plugin",
+      "@evergreen-dev/backstage-plugin-backend",
+      "@evergreen-dev/backstage-plugin-common"
+    ]
+  },
+  "sideEffects": false,
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean"
+  },
+  "dependencies": {
+    "@evergreen-dev/backstage-plugin-common": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@backstage/catalog-model": "^1.0.0",
+    "@backstage/core-components": "^0.14.0 || ^0.15.0 || ^0.16.0 || ^0.17.0",
+    "@backstage/core-plugin-api": "^1.0.0",
+    "@backstage/plugin-catalog-react": "^1.0.0",
+    "@material-ui/core": "^4.12.0",
+    "react": "^17.0.0 || ^18.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0"
+  },
+  "devDependencies": {
+    "@backstage/catalog-model": "^1.7.0",
+    "@backstage/cli": "^0.30.0",
+    "@backstage/core-components": "^0.16.0",
+    "@backstage/core-plugin-api": "^1.10.0",
+    "@backstage/plugin-catalog-react": "^1.14.0",
+    "@material-ui/core": "^4.12.4",
+    "@types/react": "^18.3.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ]
+}

package/src/api.ts

@@ -0,0 +1,52 @@
+import {
+  createApiRef,
+  type ConfigApi,
+  type DiscoveryApi,
+  type FetchApi,
+} from "@backstage/core-plugin-api";
+
+import type { PortalCatalog, PortalService } from "@evergreen-dev/backstage-plugin-common";
+
+export const evergreenApiRef = createApiRef<EvergreenApi>({
+  id: "plugin.evergreen.service",
+});
+
+export interface EvergreenApi {
+  getCatalog(): Promise<PortalCatalog>;
+  getService(servicePath: string): Promise<PortalService>;
+}
+
+export class EvergreenClient implements EvergreenApi {
+  private readonly discoveryApi: DiscoveryApi;
+  private readonly fetchApi: FetchApi;
+
+  constructor(options: { discoveryApi: DiscoveryApi; fetchApi: FetchApi; configApi?: ConfigApi }) {
+    this.discoveryApi = options.discoveryApi;
+    this.fetchApi = options.fetchApi;
+  }
+
+  private async baseUrl(): Promise<string> {
+    return this.discoveryApi.getBaseUrl("evergreen");
+  }
+
+  async getCatalog(): Promise<PortalCatalog> {
+    const response = await this.fetchApi.fetch(`${await this.baseUrl()}/catalog`);
+    if (!response.ok) {
+      throw new Error(`Evergreen catalog request failed: HTTP ${response.status}`);
+    }
+    return (await response.json()) as PortalCatalog;
+  }
+
+  async getService(servicePath: string): Promise<PortalService> {
+    const url = new URL(`${await this.baseUrl()}/services`);
+    url.searchParams.set("path", servicePath);
+    const response = await this.fetchApi.fetch(url.toString());
+    if (response.status === 404) {
+      throw new Error(`No Evergreen portal service matches ${servicePath}`);
+    }
+    if (!response.ok) {
+      throw new Error(`Evergreen service request failed: HTTP ${response.status}`);
+    }
+    return (await response.json()) as PortalService;
+  }
+}

package/src/components/LifecycleRiskCard.tsx

@@ -0,0 +1,115 @@
+import { useEntity } from "@backstage/plugin-catalog-react";
+import {
+  InfoCard,
+  Progress,
+  ResponseErrorPanel,
+  StructuredMetadataTable,
+} from "@backstage/core-components";
+import { useApi } from "@backstage/core-plugin-api";
+import { Link, Typography } from "@material-ui/core";
+import React from "react";
+
+import {
+  SERVICE_PATH_ANNOTATION,
+  SEVERITIES,
+  highestSeverity,
+  totalFindings,
+  type PortalService,
+} from "@evergreen-dev/backstage-plugin-common";
+import { evergreenApiRef } from "../api";
+
+type LoadState =
+  | { status: "loading" }
+  | { status: "missing-annotation" }
+  | { status: "error"; error: Error }
+  | { status: "ready"; service: PortalService };
+
+function useLifecycleRisk(): LoadState {
+  const { entity } = useEntity();
+  const api = useApi(evergreenApiRef);
+  const servicePath = entity.metadata.annotations?.[SERVICE_PATH_ANNOTATION];
+  const [state, setState] = React.useState<LoadState>(
+    servicePath ? { status: "loading" } : { status: "missing-annotation" },
+  );
+
+  React.useEffect(() => {
+    if (!servicePath) {
+      setState({ status: "missing-annotation" });
+      return undefined;
+    }
+    let cancelled = false;
+    setState({ status: "loading" });
+    api
+      .getService(servicePath)
+      .then((service) => {
+        if (!cancelled) setState({ status: "ready", service });
+      })
+      .catch((error: unknown) => {
+        if (!cancelled) {
+          setState({
+            status: "error",
+            error: error instanceof Error ? error : new Error(String(error)),
+          });
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [api, servicePath]);
+
+  return state;
+}
+
+export function LifecycleRiskCard() {
+  const state = useLifecycleRisk();
+
+  if (state.status === "missing-annotation") {
+    return (
+      <InfoCard title="Evergreen lifecycle risk">
+        <Typography variant="body2">
+          Add the <code>{SERVICE_PATH_ANNOTATION}</code> annotation on this
+          component, set to the scanned path from{" "}
+          <code>evergreen export --format portal</code>.
+        </Typography>
+      </InfoCard>
+    );
+  }
+
+  if (state.status === "loading") {
+    return (
+      <InfoCard title="Evergreen lifecycle risk">
+        <Progress />
+      </InfoCard>
+    );
+  }
+
+  if (state.status === "error") {
+    return (
+      <InfoCard title="Evergreen lifecycle risk">
+        <ResponseErrorPanel error={state.error} />
+      </InfoCard>
+    );
+  }
+
+  const { service } = state;
+  const metadata: Record<string, React.ReactNode> = {
+    Path: service.path,
+    Findings: String(totalFindings(service)),
+    Highest: highestSeverity(service),
+    "Next end of life": service.nextEndOfLife ?? "—",
+    Report: (
+      <Link href={service.reportLink} target="_blank" rel="noopener noreferrer">
+        Open Evergreen report
+      </Link>
+    ),
+  };
+  for (const severity of SEVERITIES) {
+    metadata[severity] = String(service.severities[severity]);
+  }
+
+  return (
+    <InfoCard title="Evergreen lifecycle risk" deepLink={{ title: "Report", link: service.reportLink }}>
+      <StructuredMetadataTable metadata={metadata} />
+    </InfoCard>
+  );
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export {
+  evergreenPlugin,
+  EntityEvergreenLifecycleCard,
+} from "./plugin";
+export { evergreenApiRef, EvergreenClient } from "./api";
+export type { EvergreenApi } from "./api";
+export {
+  PORTAL_SCHEMA_VERSION,
+  SERVICE_PATH_ANNOTATION,
+  findService,
+  highestSeverity,
+  totalFindings,
+} from "@evergreen-dev/backstage-plugin-common";
+export type {
+  PortalCatalog,
+  PortalService,
+  PortalSeverityCounts,
+  Severity,
+} from "@evergreen-dev/backstage-plugin-common";

package/src/plugin.ts

@@ -0,0 +1,40 @@
+import {
+  createApiFactory,
+  createComponentExtension,
+  createPlugin,
+  discoveryApiRef,
+  fetchApiRef,
+  configApiRef,
+} from "@backstage/core-plugin-api";
+
+import { EvergreenClient, evergreenApiRef } from "./api";
+
+export const evergreenPlugin = createPlugin({
+  id: "evergreen",
+  apis: [
+    createApiFactory({
+      api: evergreenApiRef,
+      deps: {
+        discoveryApi: discoveryApiRef,
+        fetchApi: fetchApiRef,
+        configApi: configApiRef,
+      },
+      factory: ({ discoveryApi, fetchApi }) =>
+        new EvergreenClient({ discoveryApi, fetchApi }),
+    }),
+  ],
+});
+
+/**
+ * Entity card that shows lifecycle-risk counts, the next end-of-life date, and a report link
+ * for the component's `evergreen.io/service-path` annotation.
+ */
+export const EntityEvergreenLifecycleCard = evergreenPlugin.provide(
+  createComponentExtension({
+    name: "EntityEvergreenLifecycleCard",
+    component: {
+      lazy: () =>
+        import("./components/LifecycleRiskCard").then((m) => m.LifecycleRiskCard),
+    },
+  }),
+);

package/src/types.ts

@@ -0,0 +1,15 @@
+export type {
+  PortalCatalog,
+  PortalService,
+  PortalSeverityCounts,
+  Severity,
+} from "@evergreen-dev/backstage-plugin-common";
+
+export {
+  PORTAL_SCHEMA_VERSION,
+  SERVICE_PATH_ANNOTATION,
+  SEVERITIES,
+  findService,
+  highestSeverity,
+  totalFindings,
+} from "@evergreen-dev/backstage-plugin-common";