Add descriptions for NodeTypes (#1044)

* Add descriptions for NodeTypes

As highlighted by @decentralion in issue #807, we need descriptions for Node and
Edge types in the UI to explain to users what each Node and Edge type does. This
PR modifies the type definition for `NodeType` and adds a `+description: string`
field, then updates all NodeTypes throughout the codebase with descriptions.

Test plan:

Verify that all tests pass and the descriptions makes sense.

src/analysis/fallbackDeclaration.js

@@ -13,6 +13,8 @@ export const fallbackNodeType: NodeType = Object.freeze({
   pluralName: "nodes",
   prefix: NodeAddress.empty,
   defaultWeight: 1,
+  description:
+    "The fallback NodeType for nodes which don't have any other type",
 });
 
 export const fallbackEdgeType: EdgeType = Object.freeze({

src/analysis/types.js

@@ -66,6 +66,9 @@ export type NodeType = {|
   // normal importance", and the weights scale linearly from there (i.e. 2
   // means twice as important).
   +defaultWeight: number,
+  // The `description` property should be a human-readable string that makes
+  // it clear to a user what each NodeType does
+  +description: string,
 |};
 
 /**

src/explorer/pagerankTable/Aggregation.test.js

@@ -149,6 +149,7 @@ describe("explorer/pagerankTable/Aggregation", () => {
       pluralName: "whatDoth",
       defaultWeight: 1,
       prefix: NodeAddress.empty,
+      description: "An example NodeType for testing purposes",
     };
     const edgeType: EdgeType = {
       forwardName: "marsellus",

src/explorer/pagerankTable/aggregate.test.js

@@ -1,6 +1,6 @@
 // @flow
 
-import {EdgeAddress, NodeAddress} from "../../core/graph";
+import {EdgeAddress, NodeAddress, type NodeAddressT} from "../../core/graph";
 import * as NullUtil from "../../util/null";
 import {
   aggregateByNodeType,
@@ -9,42 +9,51 @@ import {
   aggregateFlat,
   aggregationKey,
 } from "./aggregate";
+import type {NodeType} from "../../analysis/types";
 
 describe("explorer/pagerankTable/aggregate", () => {
   // TODO: If making major modifications to these tests, consider switching
   // from the hand-maintained connections and types, and instead use the demo
   // adadpters from app/adapters/demoAdapters
   function example() {
-    const nodes = {
+    const nodes: {+[string]: NodeAddressT} = {
       root: NodeAddress.fromParts(["root"]),
       zap: NodeAddress.fromParts(["zap"]),
       kif: NodeAddress.fromParts(["kif"]),
     };
 
-    const nodeTypes = {
+    const nodeTypes: {+[string]: NodeType} = {
       root: {
         name: "root",
         pluralName: "roots",
         prefix: nodes.root,
         defaultWeight: 0,
+        description:
+          "This NodeType corresponds to the node with the address named `root`",
       },
       zap: {
         name: "zap",
         pluralName: "zaps",
         prefix: nodes.zap,
         defaultWeight: 0,
+        description:
+          "This NodeType corresponds to the node with the address named `zap`",
       },
       kif: {
         name: "kif",
         pluralName: "kifs",
         prefix: nodes.kif,
         defaultWeight: 0,
+        description:
+          "This NodeType corresponds to the node with the address named `kif`",
       },
       empty: {
         name: "empty",
         pluralName: "empties",
         prefix: NodeAddress.empty,
         defaultWeight: 0,
+        description:
+          "This NodeType is for an empty address, which matches every node",
       },
     };
 

src/plugins/demo/declaration.js

@@ -11,6 +11,7 @@ export const inserterNodeType: NodeType = Object.freeze({
   pluralName: "inserters",
   prefix: NodeAddress.fromParts(["factorio", "inserter"]),
   defaultWeight: 1,
+  description: "Nodes for Factorio inserter objects in demo plugin",
 });
 
 export const machineNodeType: NodeType = Object.freeze({
@@ -18,6 +19,7 @@ export const machineNodeType: NodeType = Object.freeze({
   pluralName: "machines",
   prefix: NodeAddress.fromParts(["factorio", "machine"]),
   defaultWeight: 2,
+  description: "Nodes for Factorio machine objects in demo plugin",
 });
 
 export const assemblesEdgeType: EdgeType = Object.freeze({

src/plugins/git/declaration.js

@@ -1,14 +1,16 @@
 // @flow
 
 import type {PluginDeclaration} from "../../analysis/pluginDeclaration";
+import type {NodeType} from "../../analysis/types";
 import * as N from "./nodes";
 import * as E from "./edges";
 
-const commitNodeType = Object.freeze({
+const commitNodeType: NodeType = Object.freeze({
   name: "Commit",
   pluralName: "Commits",
   prefix: N.Prefix.commit,
   defaultWeight: 2,
+  description: "NodeType representing a git commit",
 });
 
 const hasParentEdgeType = Object.freeze({

src/plugins/github/declaration.js

@@ -9,6 +9,7 @@ const repoNodeType = Object.freeze({
   pluralName: "Repositories",
   prefix: N.Prefix.repo,
   defaultWeight: 4,
+  description: "NodeType for a GitHub repository",
 });
 
 const issueNodeType = Object.freeze({
@@ -16,6 +17,7 @@ const issueNodeType = Object.freeze({
   pluralName: "Issues",
   prefix: N.Prefix.issue,
   defaultWeight: 2,
+  description: "NodeType for a GitHub issue",
 });
 
 const pullNodeType = Object.freeze({
@@ -23,6 +25,7 @@ const pullNodeType = Object.freeze({
   pluralName: "Pull requests",
   prefix: N.Prefix.pull,
   defaultWeight: 4,
+  description: "NodeType for a GitHub pull request",
 });
 
 const reviewNodeType = Object.freeze({
@@ -30,6 +33,7 @@ const reviewNodeType = Object.freeze({
   pluralName: "Pull request reviews",
   prefix: N.Prefix.review,
   defaultWeight: 1,
+  description: "NodeType for a GitHub code review",
 });
 
 const commentNodeType = Object.freeze({
@@ -37,6 +41,7 @@ const commentNodeType = Object.freeze({
   pluralName: "Comments",
   prefix: N.Prefix.comment,
   defaultWeight: 1,
+  description: "NodeType for a GitHub comment",
 });
 
 const userNodeType = Object.freeze({
@@ -44,6 +49,7 @@ const userNodeType = Object.freeze({
   pluralName: "Users",
   prefix: N.Prefix.user,
   defaultWeight: 1,
+  description: "NodeType for a GitHub user",
 });
 
 const botNodeType = Object.freeze({
@@ -51,6 +57,7 @@ const botNodeType = Object.freeze({
   pluralName: "Bots",
   prefix: N.Prefix.bot,
   defaultWeight: 0.25,
+  description: "NodeType for a GitHub bot account",
 });
 
 const nodeTypes = Object.freeze([