From 7240ec3232f5ca9b4c5d13ef02ad3ca80cd4c687 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 6 Apr 2023 14:56:44 +0200
Subject: [PATCH] cli-node: document and refactor PackageGraph

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 packages/cli-node/src/index.ts                |  1 +
 .../cli-node/src/monorepo/PackageGraph.ts     | 65 ++++++++++++++++---
 packages/cli-node/src/monorepo/entryPoints.ts |  4 +-
 packages/cli-node/src/monorepo/index.ts       |  4 +-
 4 files changed, 62 insertions(+), 12 deletions(-)

diff --git a/packages/cli-node/src/index.ts b/packages/cli-node/src/index.ts
index ef43d7bff7..1d3f3ec2ed 100644
--- a/packages/cli-node/src/index.ts
+++ b/packages/cli-node/src/index.ts
@@ -21,4 +21,5 @@
  */
 
 export * from './git';
+export * from './monorepo';
 export * from './roles';
diff --git a/packages/cli-node/src/monorepo/PackageGraph.ts b/packages/cli-node/src/monorepo/PackageGraph.ts
index c01d76c11f..421c49f9b9 100644
--- a/packages/cli-node/src/monorepo/PackageGraph.ts
+++ b/packages/cli-node/src/monorepo/PackageGraph.ts
@@ -22,9 +22,16 @@ import { GitUtils } from '../git';
 import { Lockfile } from './Lockfile';
 import { JsonValue } from '@backstage/types';
 
-type PackageJSON = Package['packageJson'];
+/**
+ * Known fields in Backstage package.json files.
+ *
+ * @public
+ */
+export interface BackstagePackageJson {
+  name: string;
+  version: string;
+  private?: boolean;
 
-export interface ExtendedPackageJSON extends PackageJSON {
   main?: string;
   module?: string;
   types?: string;
@@ -52,20 +59,43 @@ export interface ExtendedPackageJSON extends PackageJSON {
     alphaTypes?: string;
     betaTypes?: string;
   };
+
+  dependencies?: {
+    [key: string]: string;
+  };
+  peerDependencies?: {
+    [key: string]: string;
+  };
+  devDependencies?: {
+    [key: string]: string;
+  };
+  optionalDependencies?: {
+    [key: string]: string;
+  };
 }
 
-export type ExtendedPackage = {
+/**
+ * A local Backstage monorepo package
+ *
+ * @public
+ */
+export type BackstagePackage = {
   dir: string;
-  packageJson: ExtendedPackageJSON;
+  packageJson: BackstagePackageJson;
 };
 
+/**
+ * A local package in the monorepo package graph.
+ *
+ * @public
+ */
 export type PackageGraphNode = {
   /** The name of the package */
   name: string;
   /** The directory of the package */
   dir: string;
   /** The package data of the package itself */
-  packageJson: ExtendedPackageJSON;
+  packageJson: BackstagePackageJson;
 
   /** All direct local dependencies of the package */
   allLocalDependencies: Map<string, PackageGraphNode>;
@@ -90,12 +120,23 @@ export type PackageGraphNode = {
   localOptionalDependents: Map<string, PackageGraphNode>;
 };
 
+/**
+ * Represents a local Backstage monorepo package graph.
+ *
+ * @public
+ */
 export class PackageGraph extends Map<string, PackageGraphNode> {
-  static async listTargetPackages(): Promise<ExtendedPackage[]> {
+  /**
+   * Lists all local packages in a monorepo.
+   */
+  static async listTargetPackages(): Promise<BackstagePackage[]> {
     const { packages } = await getPackages(paths.targetDir);
-    return packages as ExtendedPackage[];
+    return packages as BackstagePackage[];
   }
 
+  /**
+   * Creates a package graph from a list of local packages.
+   */
   static fromPackages(packages: Package[]): PackageGraph {
     const graph = new PackageGraph();
 
@@ -112,7 +153,7 @@ export class PackageGraph extends Map<string, PackageGraphNode> {
       graph.set(name, {
         name,
         dir: pkg.dir,
-        packageJson: pkg.packageJson as ExtendedPackageJSON,
+        packageJson: pkg.packageJson as BackstagePackageJson,
 
         allLocalDependencies: new Map(),
         publishedLocalDependencies: new Map(),
@@ -210,6 +251,14 @@ export class PackageGraph extends Map<string, PackageGraphNode> {
     return targets;
   }
 
+  /**
+   * Lists all packages that have changed since a given git ref.
+   *
+   * @remarks
+   *
+   * If the `analyzeLockfile` option is set to true, the change detection will
+   * also consider changes to the dependency management lockfile.
+   */
   async listChangedPackages(options: {
     ref: string;
     analyzeLockfile?: boolean;
diff --git a/packages/cli-node/src/monorepo/entryPoints.ts b/packages/cli-node/src/monorepo/entryPoints.ts
index 1e1fd7ed27..0ccbea8708 100644
--- a/packages/cli-node/src/monorepo/entryPoints.ts
+++ b/packages/cli-node/src/monorepo/entryPoints.ts
@@ -15,7 +15,7 @@
  */
 
 import { extname } from 'path';
-import { ExtendedPackageJSON } from './PackageGraph';
+import { BackstagePackageJson } from './PackageGraph';
 
 export interface EntryPoint {
   mount: string;
@@ -47,7 +47,7 @@ function parseEntryPoint(mount: string, path: string): EntryPoint {
   return { mount, path, name, ext: extname(path) };
 }
 
-export function readEntryPoints(pkg: ExtendedPackageJSON): Array<EntryPoint> {
+export function readEntryPoints(pkg: BackstagePackageJson): Array<EntryPoint> {
   const exp = pkg.exports;
   if (typeof exp === 'string') {
     return [defaultIndex];
diff --git a/packages/cli-node/src/monorepo/index.ts b/packages/cli-node/src/monorepo/index.ts
index 7156975c07..8a3eae3508 100644
--- a/packages/cli-node/src/monorepo/index.ts
+++ b/packages/cli-node/src/monorepo/index.ts
@@ -17,6 +17,6 @@
 export { PackageGraph } from './PackageGraph';
 export type {
   PackageGraphNode,
-  ExtendedPackage,
-  ExtendedPackageJSON,
+  BackstagePackage,
+  BackstagePackageJson,
 } from './PackageGraph';