feat: added custom field support assigment (#51)

Added the ability to add a custom project field when assigning an issue to a project.

This commit closes #44 

Moved more of the logic to the `synchronizer` and enhanced the tests to include those business logic changes.

Created an evaluated new GraphQL query for GitHub's project API.

Co-authored-by: Przemek Rzad <[email protected]>

Author: Bullrich

action.yml

@@ -7,7 +7,16 @@ branding:
 inputs:
   project:
     required: true
+    description: The number of the project which the issues will be synced to
     type: number
+  project_field:
+    required: false
+    description: The name of the project field that will be set to project_value
+    type: string
+  project_value:
+    required: false
+    description: The value which will be set in the project_field
+    type: string
   GITHUB_TOKEN:
     required: true
     type: string

package.json

@@ -28,7 +28,7 @@
   },
   "devDependencies": {
     "@octokit/graphql-schema": "^12.41.1",
-    "@types/jest": "^29.2.5",
+    "@types/jest": "^29.2.6",
     "jest": "^29.3.1",
     "jest-mock-extended": "^3.0.1",
     "opstooling-js-style": "https://github.com/paritytech/opstooling-js-style#c298d0f732d93712e4397fd53baa3317a3022c8c",

src/github/CoreLogger.ts

@@ -7,7 +7,7 @@ export class CoreLogger implements ILogger {
   info(message: string): void {
     core.info(message);
   }
-  warning(message: string): void {
+  warning(message: string | Error): void {
     core.warning(message);
   }
   error(message: string | Error): void {

src/github/projectKit.ts

@@ -1,8 +1,9 @@
 import { graphql } from "@octokit/graphql";
 
-import { ILogger, IProjectApi, Issue, Repository } from "./types";
+import { FieldValues, ILogger, IProjectApi, Issue, Repository } from "./types";
 
 type NodeData = { id: string; title: string };
+type FieldData = { name: string; id: string; options?: { name: string; id: string }[] };
 
 export const PROJECT_V2_QUERY: string = `
 query($organization: String!, $number: Int!) {
@@ -25,6 +26,41 @@ mutation($project: ID!, $issue: ID!) {
 }
 `;
 
+export const PROJECT_FIELD_ID_QUERY: string = `
+query($project: ID!) {
+  node(id: $project) {
+    ... on ProjectV2 {
+      fields(first: 20) { 
+        nodes {
+          ... on ProjectV2Field {
+            id
+            name
+          }
+          ... on ProjectV2IterationField {
+            id
+            name
+            configuration {
+              iterations {
+                startDate
+                id
+              }
+            }
+          }
+          ... on ProjectV2SingleSelectField {
+            id
+            name
+            options {
+              id
+              name
+            }
+          }
+        }
+      }
+    }
+  }
+}
+`;
+
 export const UPDATE_PROJECT_V2_ITEM_FIELD_VALUE_QUERY: string = `
 mutation (
   $project: ID!
@@ -65,20 +101,38 @@ export class ProjectKit implements IProjectApi {
     private readonly logger: ILogger,
   ) {}
 
-  /* 
-  changeIssueStateInProject(issueCardId: number, state: "todo" | "in progress" | "blocked" | "done"): Promise<void> {
-    return this.gql(UPDATE_STATE_IN_PROJECT_QUERY, {
-      project: this.projectNumber,
-      item: issueCardId,
-      targetField: "Status",
-      targetFieldValue: state,
-    });
-  } */
+  async changeIssueStateInProject(issueCardId: string, project: NodeData, fields: FieldValues): Promise<void> {
+    try {
+      const op = await this.gql(UPDATE_PROJECT_V2_ITEM_FIELD_VALUE_QUERY, {
+        project: project.id,
+        item: issueCardId,
+        targetField: fields.field,
+        targetFieldValue: fields.value,
+      });
+
+      this.logger.debug("Returned " + JSON.stringify(op));
+    } catch (e) {
+      throw new Error("Failed while executing the 'UPDATE_PROJECT_V2_ITEM_FIELD_VALUE_QUERY' query", { cause: e });
+    }
+  }
 
   /**
-   * Fetches the node id from the project id and caches it.
-   * @returns node_id of the project. This value never changes so caching it per instance is effective
+   * Get all the project fields in a project, with their node ids and available options
+   * @returns A collection of all the fields available in the issue item
    */
+  async getProjectFields(projectId: string): Promise<FieldData[]> {
+    try {
+      type returnType = { node: { fields: { nodes: FieldData[] } } };
+      const projectData = await this.gql<returnType>(PROJECT_FIELD_ID_QUERY, { project: projectId });
+
+      this.logger.debug("correct node data: " + JSON.stringify(projectData.node.fields.nodes[0]));
+      return projectData.node.fields.nodes;
+    } catch (e) {
+      this.logger.error("Failed while executing the 'PROJECT_V2_QUERY' query");
+      throw e;
+    }
+  }
+
   async fetchProjectData(): Promise<NodeData> {
     if (this.projectNode) {
       return this.projectNode;
@@ -95,8 +149,7 @@ export class ProjectKit implements IProjectApi {
 
       return projectData.organization.projectV2;
     } catch (e) {
-      this.logger.error("Failed while executing the 'PROJECT_V2_QUERY' query");
-      throw e;
+      throw new Error("Failed while executing the 'PROJECT_V2_QUERY' query", { cause: e });
     }
   }
 
@@ -109,39 +162,55 @@ export class ProjectKit implements IProjectApi {
     await this.gql(UPDATE_PROJECT_V2_ITEM_FIELD_VALUE_QUERY, { project, item, targetField, targetFieldValue });
   }
 
-  async assignIssueToProject(issue: Issue, projectId: string): Promise<boolean> {
+  async assignIssueToProject(issue: Issue, projectId: string): Promise<string> {
     try {
       const migration = await this.gql<{ addProjectV2ItemById: { item: { id: string } } }>(
         ADD_PROJECT_V2_ITEM_BY_ID_QUERY,
         { project: projectId, issue: issue.node_id },
       );
 
-      return !!migration.addProjectV2ItemById.item.id;
+      return migration.addProjectV2ItemById.item.id;
     } catch (e) {
-      this.logger.error("Failed while executing 'ADD_PROJECT_V2_ITEM_BY_ID_QUERY' query");
-      throw e;
+      throw new Error("Failed while executing 'ADD_PROJECT_V2_ITEM_BY_ID_QUERY' query", { cause: e });
     }
   }
 
-  async addIssueToProject(issue: Issue, project: NodeData): Promise<boolean> {
-    this.logger.info(`Syncing issue #${issue.number} for ${project.title}`);
+  async fetchProjectFieldNodeValues(project: NodeData, projectFields?: FieldValues): Promise<FieldValues> {
+    if (!projectFields) {
+      throw new Error("'projectsFields' is null!");
+    }
 
-    return await this.assignIssueToProject(issue, project.id);
-  }
+    const projectFieldData = await this.getProjectFields(project.id);
 
-  async assignIssue(issue: Issue): Promise<boolean> {
-    const project = await this.fetchProjectData();
+    const { field, value } = projectFields;
 
-    return await this.addIssueToProject(issue, project);
+    // ? Should we use .localeCompare here?
+    const customField = projectFieldData.find(({ name }) => name.toUpperCase() === field.toUpperCase());
 
-    // TODO: Assign targetField
-  }
+    // check that this custom field exists and it has available options to set up
+    if (!customField) {
+      throw new Error(`Field ${field} does not exist!`);
+    } else if (!customField.options) {
+      throw new Error(`Field ${field} does not have any available options!.` + "Please add options to set values");
+    }
 
-  async assignIssues(issues: Issue[]): Promise<boolean[]> {
-    const project = await this.fetchProjectData();
+    this.logger.debug(`Custom field '${field}' was found.`);
 
-    const issueAssigment = issues.map((issue) => this.addIssueToProject(issue, project));
+    // search for the node element with the correct name.
+    const fieldOption = customField.options.find(({ name }) => name.toUpperCase() === value.toUpperCase());
+    if (!fieldOption) {
+      const valuesArray = customField.options.map((options) => options.name);
+      throw new Error(`Project value '${value}' does not exist. Available values are ${JSON.stringify(valuesArray)}`);
+    }
 
-    return await Promise.all(issueAssigment);
+    this.logger.debug(`Field options '${value}' was found.`);
+
+    return { field: customField.id, value: fieldOption.id };
+  }
+
+  async assignIssue(issue: Issue, project: NodeData): Promise<string> {
+    this.logger.info(`Syncing issue #${issue.number} for ${project.title}`);
+
+    return await this.assignIssueToProject(issue, project.id);
   }
 }

src/github/types.ts

@@ -2,20 +2,34 @@ export type Repository = { owner: string; repo: string };
 
 export type Issue = { number: number; node_id: string };
 
+/** Key value pair with the name/id of a field and the name/id of its value */
+export type FieldValues = { field: string; value: string };
+
+export type NodeData = { id: string; title: string };
+
 export interface IProjectApi {
+  /**
+   * Fetches the node id from the project id and caches it.
+   * @returns node_id of the project. This value never changes so caching it per instance is effective
+   */
+  fetchProjectData(): Promise<NodeData>;
   /**
    * Assign an issue to a project
    * @param issue The issue object which has the number and the node_id
+   * @returns the issueCardId of the created issue. This ID is used in changeIssueStateInProject.
+   * @see changeIssueStateInProject
    */
-  assignIssue(issue: Issue): Promise<boolean>;
-
+  assignIssue(issue: Issue, project: NodeData): Promise<string>;
   /**
-   * Assign several issues to a project
-   * @param issues The issue object collection which has the number and the node_id
+   * Fetches the available fields for a project board and filters to find the node ids of the field and value
+   * If either the field or the value don't exist, it will fail with an exception
+   * @param project The node data of the project
+   * @param projectFields The literal names of the fields to be modified
+   * @returns The id of both the field and the value
    */
-  assignIssues(issues: Issue[]): Promise<boolean[]>;
+  fetchProjectFieldNodeValues(project: NodeData, projectFields?: FieldValues): Promise<FieldValues>;
   // getProjectIdFromIssue(issueId: number): Promise<number>;
-  // changeIssueStateInProject(issueId: number, state: "todo" | "in progress" | "blocked" | "done"): Promise<boolean>;
+  changeIssueStateInProject(issueCardId: string, project: NodeData, fields: FieldValues): Promise<void>;
 }
 
 /** Class managing the instance of issues */
@@ -34,7 +48,7 @@ export interface IIssues {
 
 export interface ILogger {
   info(message: string): void;
-  warning(message: string): void;
+  warning(message: string | Error): void;
   error(message: string | Error): void;
   /** Only posts messages if the action is ran in debug mode */
   debug(message: string): void;

src/main.ts

@@ -1,18 +1,28 @@
-import { getInput, info, setFailed } from "@actions/core";
+import { debug, error, getInput, info, setFailed } from "@actions/core";
 import { context, getOctokit } from "@actions/github";
 
 import { CoreLogger } from "./github/CoreLogger";
 import { IssueApi } from "./github/issueKit";
 import { ProjectKit } from "./github/projectKit";
 import { GitHubContext, Synchronizer } from "./synchronizer";
 
+const getProjectFieldValues = (): { field: string; value: string } | undefined => {
+  const field = getInput("project_field");
+  const value = getInput("project_value");
+
+  if (field && value) {
+    return { field, value };
+  } else {
+    debug("'project_field' and 'project_value' are empty.");
+  }
+};
+
 //* * Generates the class that will handle the project logic */
 const generateSynchronizer = (): Synchronizer => {
   const repoToken = getInput("GITHUB_TOKEN", { required: true });
   const orgToken = getInput("PROJECT_TOKEN", { required: true });
 
   const projectNumber = parseInt(getInput("project", { required: true }));
-  // TODO: Add support for custom project fields (https://docs.github.com/en/issues/planning-and-tracking-with-projects/understanding-fields)
 
   const { repo } = context;
 
@@ -27,6 +37,7 @@ const generateSynchronizer = (): Synchronizer => {
 
 const synchronizer = generateSynchronizer();
 
+const projectFields = getProjectFieldValues();
 const { issue } = context.payload;
 const parsedContext: GitHubContext = {
   eventName: context.eventName,
@@ -35,9 +46,27 @@ const parsedContext: GitHubContext = {
     inputs: context.payload.inputs,
     issue: issue ? { number: issue.number, node_id: issue.node_id as string } : undefined,
   },
+  config: { projectField: projectFields },
+};
+
+const errorHandler = (e: Error) => {
+  let er = e;
+  setFailed(e);
+  while (er !== null) {
+    debug(`Stack -> ${er.stack as string}`);
+    if (er.cause != null) {
+      debug("Error has a nested error. Displaying.");
+      er = er.cause as Error;
+      error(er);
+    } else {
+      break;
+    }
+  }
 };
 
 synchronizer
   .synchronizeIssue(parsedContext)
-  .then(() => info("Finished"))
-  .catch(setFailed);
+  .then(() => {
+    info("Operation finished successfully!");
+  })
+  .catch(errorHandler);