@infrascan/shared-types 0.2.4 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @infrascan/shared-types
 
+## 0.4.0
+
+### Minor Changes
+
+- [#77](https://github.com/infrascan/infrascan/pull/77) [`21d4ecf`](https://github.com/infrascan/infrascan/commit/21d4ecf4b7fec31f4ac7b2cc5857aa5d2b725075) Thanks [@lfarrel6](https://github.com/lfarrel6)! - Add in-memory graph model to decouple the infrascan packages from a single graphing library, and to make graph manipulation easier
+
+## 0.3.0
+
+### Minor Changes
+
+- [#75](https://github.com/infrascan/infrascan/pull/75) [`4634235`](https://github.com/infrascan/infrascan/commit/4634235d61bd6bd817c6fb9e62add778218b69b6) Thanks [@lfarrel6](https://github.com/lfarrel6)! - Add graph model interface to shared types package
+
 ## 0.2.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infrascan/shared-types",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "description": "Shared types for multiple infrascan packages",
   "main": "src/index.ts",
   "scripts": {

package/src/api.ts

@@ -1,6 +1,6 @@
 import type { AwsCredentialIdentityProvider, RetryStrategy, RetryStrategyV2 } from "@aws-sdk/types";
 
-import type { GraphEdge, GraphNode } from "./graph";
+import type { SelectedEdge, SelectedNode } from "./graph";
 import type { BaseEdgeResolver } from "./config";
 
 /**
@@ -85,9 +85,9 @@ type GetterFn<T, P extends Provider> = (
 type GetNodeFn<T extends Provider> = (
   stateConnector: Connector,
   context: ProviderContextMap[T],
-) => Promise<GraphNode[]>;
+) => Promise<SelectedNode[]>;
 
-type GetEdgeFn = (stateConnector: Connector) => Promise<GraphEdge[]>;
+type GetEdgeFn = (stateConnector: Connector) => Promise<SelectedEdge[]>;
 
 export type Provider = "aws";
 
@@ -106,15 +106,6 @@ export type ProviderContext<T extends Provider> = {
   context: ProviderContextMap[T];
 };
 
-type FormatNodeFn<P extends Provider> = (
-  node: GraphNode,
-  context: ProviderContextMap[P],
-) => GraphNode;
-type FormatEdgeFn<P extends Provider> = (
-  node: GraphEdge,
-  context: ProviderContextMap[P],
-) => GraphEdge;
-
 export type EntityRoleData = {
   roleArn: string;
   executor: string;
@@ -131,9 +122,7 @@ export interface ServiceModule<T, P extends Provider> {
   getters: GetterFn<T, P>[];
   nodes?: string[];
   getNodes?: GetNodeFn<P>;
-  formatNode?: FormatNodeFn<P>;
   edges?: BaseEdgeResolver[];
   getEdges?: GetEdgeFn;
-  formatEdge?: FormatEdgeFn<P>;
   getIamRoles?: GetIamRoleFn;
 }

package/src/graph.ts

@@ -1,7 +1,7 @@
 /**
  * A node returned from a state selector before its been formatted for a graphing library
  */
-export type SelectedNode = {
+export interface SelectedNode {
   id: string;
   name?: string;
   parent?: string;
@@ -9,62 +9,48 @@ export type SelectedNode = {
   rawState?: any;
 };
 
-/**
- * A node on the graph
- */
-export type GraphNode = {
-  group: "nodes";
-  id: string;
-  data: {
-    id: string;
-    type: string;
-    /**
-     * Parent node (account, region etc)
-     */
-    parent?: string;
-    name?: string;
-    service?: string;
-  };
-  /* eslint-disable @typescript-eslint/no-explicit-any */
-  metadata?: any;
-};
+export interface SelectedEdgeTarget {
+  name: string,
+  target: string
+}
 
-/**
- * An edge connecting two nodes within a graph
- */
-export type GraphEdge = {
-  group: "edges";
-  /**
-   * Unique ID for the edge
-   */
-  id?: string;
-  data: {
-    id: string;
-    name: string;
-    /**
-     * Source Node
-     */
-    source: string;
-    /**
-     * Target Node
-     */
-    target: string;
-    type: string;
-  };
-  metadata?: {
-    label: string;
-    roleArn?: string;
-    /* eslint-disable @typescript-eslint/no-explicit-any */
-    statement?: any;
-  };
+export interface SelectedEdge {
+  source: string;
+  target: string;
+  metadata?: Record<string, unknown>
 };
 
-/**
- * Generic type for elements in a graph
- */
-export type GraphElement = GraphNode | GraphEdge;
+export interface Node {
+  id: string,
+  name: string,
+  metadata: Record<string, unknown>;
+  service?: string,
+  type?: string,
+  parent?: string | Node,
+  children?: Record<string, Node>,
+  incomingEdges: Record<string, Edge<Node>>,
+  outgoingEdges: Record<string, Edge<Node>>,
+}
 
-export type EdgeTarget = {
-  name: string;
-  target: string;
+export interface Edge<T extends string | Node> {
+  id: string,
+  name?: string,
+  metadata: Record<string, unknown>,
+  source: T,
+  target: T
+}
+
+export interface Graph {
+  nodes: Node[],
+  edges: Edge<Node>[],
+  addNode: (node: Pick<Node, "id" | "name" | "metadata" | "parent" | "service" | "type">) => void,
+  addEdge: (edge: Pick<Edge<string>, "name" | "source" | "target" | "metadata">) => void,
+  addChild: (parent: string, child: string) => void,
+  getNode: (id: string) => Node | undefined,
+  mapNodesById: (id: string, mapperFn: (node: Node) => Node[]) => void,
+  removeEdge: (id: string) => Edge<Node>,
+  removeNode: (id: string) => Node,
+  serialize: () => string
 };
+
+export type GraphSerializer<T> = (graph: Graph) => T;

package/src/index.ts

@@ -2,3 +2,4 @@ export * from "./api";
 export * from "./config";
 export * from "./graph";
 export * from "./scan";
+export * from "./plugins";

package/src/plugins.ts

@@ -0,0 +1,42 @@
+import { Graph } from "./graph";
+import { AwsContext } from "./api";
+
+// All supported events to trigger a plugin
+export type GraphPluginEvents = "onServiceComplete" | "onRegionComplete" | "onAccountComplete" | "onGraphComplete";
+
+/**
+ * A plugin which is called everytime a service's nodes have been added to the graph.
+ * Receives the current graph state, the service ID, and the current AWS Context.
+ */
+export type OnServiceCompletePlugin = (graph: Graph, service: string, context: AwsContext) => void | Promise<void>;
+
+/**
+ * A plugin which is called everytime a region's nodes have been added to the graph.
+ * Receives the current graph state, and the current AWS Context.
+ */
+export type OnRegionCompletePlugin = (graph: Graph, context: AwsContext) => void | Promise<void>;
+
+/**
+ * A plugin which is called everytime an account's nodes have been added to the graph.
+ * Receives the current graph state, and the current AWS Context.
+ */
+export type OnAccountCompletePlugin = (graph: Graph, context: AwsContext) => void | Promise<void>;
+
+/**
+ * A plugin which is called when the entire graph has been generated.
+ * Receives the entire graph state.
+ */
+export type OnGraphCompletePlugin = (graph: Graph) => void | Promise<void>;
+
+export type PluginEventHandlerTypes = {
+    "onServiceComplete": OnServiceCompletePlugin,
+    "onRegionComplete": OnRegionCompletePlugin,
+    "onAccountComplete": OnAccountCompletePlugin,
+    "onGraphComplete": OnGraphCompletePlugin,
+};
+
+export interface GraphPlugin<E extends GraphPluginEvents> {
+    id: string,
+    event: E,
+    handler: PluginEventHandlerTypes[E]
+}