@shopware-ag/gh-project-automation/dist/index.d.ts

Project automation for shopware

import { GitHub } from '@actions/github/lib/utils.js';
import { Context } from '@actions/github/lib/context.js';
import * as core from '@actions/core';
import * as exec from '@actions/exec';
import * as glob from '@actions/glob';
import * as io from '@actions/io';
import fetch from 'node-fetch';

type GitHubIssue = {
    id: string;
    title: string;
    number?: number;
    url?: string;
    status?: string;
    labels: Label[];
    type?: string;
    owner?: string;
    repository?: string;
    assignees?: {
        login: string;
    };
    reviewRequests?: {
        login: string;
    };
};
type GitHubComment = {
    id: string;
    author: {
        login: string;
    };
    body: string;
    url?: string;
};
type Label = {
    id: string;
    name: string;
    url: string;
    description?: string;
    color: string;
};
type Labelable = {
    id: string;
    number: number;
    title: string;
    labels: {
        nodes: [
            {
                name: string;
            }
        ];
    };
};

type JiraIssue = {
    id: string;
    title: string;
    key: string;
    url?: string;
    status?: string;
    labels: string[];
    type?: string;
};

type QueryResponse = {
    repository: {
        issues?: {
            pageInfo: {
                hasNextPage: boolean;
                endCursor: string;
            };
            nodes: [
                {
                    id: string;
                    number: number;
                    title: string;
                    labels: {
                        nodes: [
                            {
                                name: string;
                            }
                        ];
                    };
                }
            ];
        };
        pullRequests?: {
            pageInfo: {
                hasNextPage: boolean;
                endCursor: string;
            };
            nodes: [
                {
                    id: string;
                    number: number;
                    title: string;
                    labels: {
                        nodes: [
                            {
                                name: string;
                            }
                        ];
                    };
                }
            ];
        };
    };
};

type Toolkit = {
    github: InstanceType<typeof GitHub>;
    context: Context;
    core: typeof core;
    exec: typeof exec;
    glob: typeof glob;
    io: typeof io;
    fetch: typeof fetch;
};

declare function closeIssue(toolkit: Toolkit, issueId: string, reason?: string): Promise<void>;
declare function closePullRequest(toolkit: Toolkit, pullRequestId: string): Promise<void>;
declare function getLabelByName(toolkit: Toolkit, repository: string, labelName: string): Promise<Label | undefined>;
declare function addLabelToLabelable(toolkit: Toolkit, labelId: string, labelableId: string): Promise<void>;
declare function findIssueWithProjectItems(toolkit: Toolkit, number: number): Promise<{
    node_id: string;
    number: number;
    projectItems: [{
        id: string;
        project: {
            number: number;
        };
        fieldValueByName: {
            name: string;
        };
    }];
}>;
declare function findPRWithProjectItems(toolkit: Toolkit, number: number): Promise<{
    node_id: string;
    number: number;
    projectItems: [{
        project: {
            number: number;
        };
        fieldValueByName: {
            name: string;
        };
    }];
}>;
declare function setFieldValue(toolkit: Toolkit, data: {
    projectId: string;
    itemId: string;
    fieldId: string;
    valueId: string;
}): Promise<unknown>;
declare function getProjectInfo(toolkit: Toolkit, data: {
    number: number;
    organization?: string;
}): Promise<{
    node_id: string;
    title: string;
    fields: [{
        id: string;
        name: string;
        options: [{
            id: string;
            name: string;
        }];
    }];
}>;
declare function addProjectItem(toolkit: Toolkit, data: {
    projectId: string;
    issueId: string;
}): Promise<{
    node_id: string;
}>;
/**
 * getProjectIdByNumber fetches the project ID for a given project number.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param number - The project number to get the ID for.
 * @param organization - The organization name whose projects to consider.
 */
declare function getProjectIdByNumber(toolkit: Toolkit, number: number, organization?: string | null): Promise<string>;
/**
 * getIssuesByProject fetches all issues from a project.
 *
 * @remarks
 * This function uses pagination to fetch all issues from a project.
 * It will keep fetching until all issues are retrieved.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param projectId - The ID of the project to fetch issues from.
 * @param cursor - The cursor for pagination.
 * @param carry - The issues already fetched.
 */
declare function getIssuesByProject(toolkit: Toolkit, projectId: string, cursor?: string | null, carry?: GitHubIssue[] | null): Promise<GitHubIssue[]>;
/**
 * getCommentsForIssue fetches all comments for a given issue.
 *
 * @remarks
 * This function uses pagination to fetch all comments for an issue.
 * It will keep fetching until all comments are retrieved.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param issueId - The ID of the issue to fetch comments for.
 * @param cursor - The cursor for pagination.
 * @param carry - The comments already fetched.
 */
declare function getCommentsForIssue(toolkit: Toolkit, issueId: string, cursor?: string | null, carry?: GitHubComment[] | null): Promise<GitHubComment[]>;
/**
 * Gets pull requests matching the given search criteria
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param searchQuery - The GitHub search query to use
 */
declare function getPullRequests(toolkit: Toolkit, searchQuery: string): Promise<[{
    id: string;
    title: string;
    number: number;
    url: string;
    repository: {
        owner: {
            login: string;
        };
        name: string;
    };
    assignees: {
        nodes: [{
            login: string;
        }];
    };
    reviewRequests: {
        nodes: [{
            requestedReviewer: {
                login?: string;
                name?: string;
            };
        }];
    };
    closingIssuesReferences: {
        nodes: [{
            id: string;
            title: string;
            number: number;
            url: string;
            repository: {
                owner: {
                    login: string;
                };
                name: string;
            };
        }];
    };
}]>;
declare function addComment(toolkit: Toolkit, issueId: string, commentBody: string): Promise<GitHubComment>;
/**
 * getVerifiedDomainEmails fetches the verified domain emails for a user account associated with an enterprise.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param login - The login of the user.
 * @param organization - The organization name whose verified domains to consider.
 */
declare function getVerifiedDomainEmails(toolkit: Toolkit, login: string, organization: string): Promise<string[]>;

declare const jiraHost = "shopware.atlassian.net";
declare const jiraBaseUrl = "https://shopware.atlassian.net/rest/api/3";
/**
 * Makes an API call to JIRA with the provided endpoint and request body.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param endpoint - The JIRA API endpoint to call.
 * @param requestBody - The request body to send with the API call.
 *
 * @return The response from the JIRA API.
 */
declare function callJiraApi(toolkit: Toolkit, endpoint: string, requestBody: object): Promise<any>;

declare class SlackClient {
    private webClient;
    constructor(token: string);
    getUserByEmail(email: string): Promise<string | null>;
    sendIMToUser(userId: string, message: string): Promise<void>;
}

declare function getOldBranches(toolkit: Toolkit, repo: string, excludeRegex?: string, organization?: string): Promise<string[] | null>;
declare function cleanupBranches(toolkit: Toolkit, repo: string, organization?: string): Promise<void>;

declare const docIssueReference: string;
/**
 * getDevelopmentIssueForPullRequest fetches the development issue linked to a pull request.
 *
 * @remarks
 * This function searches for pull requests in the Shopware organization that match the given head and assignee.
 * It retrieves the first closing issue reference from the matching pull requests.
 * If a matching development issue is found, it returns the issue details; otherwise, it returns null.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param repo - The repository to search in, formatted as "owner/repo".
 * @param pullRequestNumber - The number of the pull request to search for.
 * @param pullRequestHead - The head branch of the pull request.
 * @param pullRequestAssignee - The assignee of the pull request.
 */
declare function getDevelopmentIssueForPullRequest(toolkit: Toolkit, repo: string, pullRequestNumber: number, pullRequestHead: string, pullRequestAssignee: string): Promise<GitHubIssue | null>;
/**
 * getEpicsInProgressByProject fetches all epics in progress from a project.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param projectId - The ID of the project to fetch issues from.
 */
declare function getEpicsInProgressByProject(toolkit: Toolkit, projectId: string): Promise<GitHubIssue[]>;
/**
 * createDocIssueComment creates a comment on a GitHub issue that references a documentation issue.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param issueId - The ID of the issue to comment on.
 * @param docIssueKey - The key of the documentation issue to reference.
 * @param content - The comment to add.
 */
declare function createDocIssueComment(toolkit: Toolkit, issueId: string, docIssueKey: string, content?: string | null): Promise<GitHubComment>;
/**
 * hasDocIssueComment checks if a GitHub issue has a comment that references a documentation issue.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param issueId - The ID of the issue to check.
 */
declare function hasDocIssueComment(toolkit: Toolkit, issueId: string): Promise<boolean>;
/**
 * referencesDocIssue checks if a comment contains a link to a documentation issue.
 *
 * @param comment - The comment to check.
 */
declare function referencesDocIssue(comment: GitHubComment): boolean;
/**
 * Cleans up needs-triage in issues and pull requests
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param dryRun - If true, only log what would be done without making changes.
 *
 * @remarks
 * This function finds all open issues and pull requests and ensures they have either:
 * - The needs-triage label, or
 * - A label starting with 'domain/' or 'service/'
 * - If an item has a `domain/` or `service/` label, remove the `needs-triage` label
 *
 * Closed items are ignored. The function handles pagination to process all items.
 */
declare function cleanupNeedsTriage(toolkit: Toolkit, dryRun?: boolean): Promise<void>;
declare function findWithProjectItems(toolkit: Toolkit): Promise<{
    node_id: string;
    number: number;
    projectItems: [{
        project: {
            number: number;
        };
        fieldValueByName: {
            name: string;
        };
    }];
}>;

/**
 * createDocumentationTask creates a documentation task in JIRA for a given GitHub issue.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param issue - The issue to create a documentation task for.
 * @param documentationProjectId - The ID of the documentation project.
 * @param description - The description of the documentation task.
 */
declare function createDocumentationTask(toolkit: Toolkit, issue: GitHubIssue, documentationProjectId?: number | null, description?: string | null): Promise<JiraIssue>;

/**
 * Sets the status of issues in projects using the provided toolkit.
 *
 * @param toolkit - The toolkit instance to interact with the project management system.
 * @param props - The properties for setting the status.
 * @param props.toStatus - The status to set the issues to.
 * @param props.fromStatus - (Optional) The status to filter issues by before setting the new status. Can be a string which has to match exactly or an instance of RegExp
 *
 * @remarks
 * This function finds issues in projects and updates their status based on the provided `toStatus`.
 * If `fromStatus` is provided, only issues with the matching status will be updated.
 * If the `toStatus` option is not found in the project's status options, the issue will be skipped.
 *
 * @example
 * ```typescript
 * await setStatusInProjects({ github, context, core, exec, glob, io, fetch }, { toStatus: 'In Progress', fromStatus: 'Done' });
 * ```
 */
declare function setStatusInProjects(toolkit: Toolkit, props: {
    toStatus: string;
    fromStatus?: string | RegExp;
}): Promise<void>;
declare function syncPriorities(toolkit: Toolkit, excludeList?: number[]): Promise<void>;
/**
 * createDocumentationTasksForProjects creates documentation tasks for all projects with the given project numbers.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param projectNumbers - The project numbers to create documentation tasks for.
 * @param organization - The organization name whose projects to consider.
 * @param documentationProjectId - The ID of the documentation project.
 * @param description - Prefix for the description of the documentation task.
 * @param comment - Prefix for the documentation task reference comment.
 */
declare function createDocumentationTasksForProjects(toolkit: Toolkit, projectNumbers: number[], organization?: string | null, documentationProjectId?: number | null, description?: string | null, comment?: string | null): Promise<void>;
declare function markStaleIssues(toolkit: Toolkit, projectNumber: number, dryRun: boolean): Promise<void>;
declare function closeStaleIssues(toolkit: Toolkit, dryRun: boolean): Promise<void>;

/**
 * manageOldPullRequests checks for old pull requests and closes them if they have been inactive for a specified number of days.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param organization - The GitHub organization to check for old pull requests.
 * @param days - Consider pull requests old after this many days of inactivity.
 * @param close - If true, the pull request will be closed after sending the reminder.
 */
declare function manageOldPullRequests(toolkit: Toolkit, organization?: string, days?: number, close?: boolean): Promise<void>;

/**
 * Sends a message to a Slack user identified by their email address.
 *
 * @param toolkit - Octokit instance. See: https://octokit.github.io/rest.js
 * @param emails - The email address(es) of the Slack user to send the message to.
 * @param message - The message to send.
 */
declare function sendSlackMessageForEMail(toolkit: Toolkit, emails: string[], message: string): Promise<void>;

export { SlackClient, addComment, addLabelToLabelable, addProjectItem, callJiraApi, cleanupBranches, cleanupNeedsTriage, closeIssue, closePullRequest, closeStaleIssues, createDocIssueComment, createDocumentationTask, createDocumentationTasksForProjects, docIssueReference, findIssueWithProjectItems, findPRWithProjectItems, findWithProjectItems, getCommentsForIssue, getDevelopmentIssueForPullRequest, getEpicsInProgressByProject, getIssuesByProject, getLabelByName, getOldBranches, getProjectIdByNumber, getProjectInfo, getPullRequests, getVerifiedDomainEmails, hasDocIssueComment, jiraBaseUrl, jiraHost, manageOldPullRequests, markStaleIssues, referencesDocIssue, sendSlackMessageForEMail, setFieldValue, setStatusInProjects, syncPriorities };
export type { GitHubComment, GitHubIssue, JiraIssue, Label, Labelable, QueryResponse, Toolkit };