diff --git a/.changeset/shaggy-readers-explain.md b/.changeset/shaggy-readers-explain.md new file mode 100644 index 0000000000..29266e5a32 --- /dev/null +++ b/.changeset/shaggy-readers-explain.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-scaffolder-backend': patch +--- + +Cleanup API report diff --git a/plugins/scaffolder-backend/api-report.md b/plugins/scaffolder-backend/api-report.md index 741851f938..3bc03c4840 100644 --- a/plugins/scaffolder-backend/api-report.md +++ b/plugins/scaffolder-backend/api-report.md @@ -33,9 +33,7 @@ import { TemplateMetadata } from '@backstage/plugin-scaffolder-common'; import { UrlReader } from '@backstage/backend-common'; import { Writable } from 'stream'; -// Warning: (ae-missing-release-tag) "ActionContext" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type ActionContext = { baseUrl?: string; logger: Logger_2; @@ -73,9 +71,7 @@ export interface CreateBuiltInActionsOptions { reader: UrlReader; } -// Warning: (ae-missing-release-tag) "createCatalogRegisterAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function createCatalogRegisterAction(options: { catalogClient: CatalogApi; integrations: ScmIntegrations; @@ -91,16 +87,12 @@ export function createCatalogRegisterAction(options: { } >; -// Warning: (ae-missing-release-tag) "createCatalogWriteAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function createCatalogWriteAction(): TemplateAction<{ filePath?: string | undefined; entity: Entity; }>; -// Warning: (ae-missing-release-tag) "createDebugLogAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function createDebugLogAction(): TemplateAction<{ message?: string | undefined; @@ -109,9 +101,7 @@ export function createDebugLogAction(): TemplateAction<{ export { createFetchCookiecutterAction }; -// Warning: (ae-missing-release-tag) "createFetchPlainAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function createFetchPlainAction(options: { reader: UrlReader; integrations: ScmIntegrations; @@ -120,9 +110,7 @@ export function createFetchPlainAction(options: { targetPath?: string | undefined; }>; -// Warning: (ae-missing-release-tag) "createFetchTemplateAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function createFetchTemplateAction(options: { reader: UrlReader; integrations: ScmIntegrations; @@ -136,16 +124,12 @@ export function createFetchTemplateAction(options: { cookiecutterCompat?: boolean | undefined; }>; -// Warning: (ae-missing-release-tag) "createFilesystemDeleteAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const createFilesystemDeleteAction: () => TemplateAction<{ files: string[]; }>; -// Warning: (ae-missing-release-tag) "createFilesystemRenameAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const createFilesystemRenameAction: () => TemplateAction<{ files: Array<{ from: string; @@ -154,9 +138,7 @@ export const createFilesystemRenameAction: () => TemplateAction<{ }>; }>; -// Warning: (ae-missing-release-tag) "createGithubActionsDispatchAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function createGithubActionsDispatchAction(options: { integrations: ScmIntegrations; githubCredentialsProvider?: GithubCredentialsProvider; @@ -172,9 +154,29 @@ export function createGithubActionsDispatchAction(options: { token?: string | undefined; }>; -// Warning: (ae-missing-release-tag) "createGithubWebhookAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) +export interface CreateGithubPullRequestActionOptions { + // (undocumented) + clientFactory?: ( + input: CreateGithubPullRequestClientFactoryInput, + ) => Promise; + // (undocumented) + githubCredentialsProvider?: GithubCredentialsProvider; + // (undocumented) + integrations: ScmIntegrationRegistry; +} + +// @public (undocumented) +export type CreateGithubPullRequestClientFactoryInput = { + integrations: ScmIntegrationRegistry; + githubCredentialsProvider?: GithubCredentialsProvider; + host: string; + owner: string; + repo: string; + token?: string; +}; + +// @public export function createGithubWebhookAction(options: { integrations: ScmIntegrationRegistry; defaultWebhookSecret?: string; @@ -190,9 +192,7 @@ export function createGithubWebhookAction(options: { token?: string | undefined; }>; -// Warning: (ae-missing-release-tag) "createPublishAzureAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function createPublishAzureAction(options: { integrations: ScmIntegrationRegistry; config: Config; @@ -204,9 +204,7 @@ export function createPublishAzureAction(options: { token?: string | undefined; }>; -// Warning: (ae-missing-release-tag) "createPublishBitbucketAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function createPublishBitbucketAction(options: { integrations: ScmIntegrationRegistry; config: Config; @@ -220,16 +218,12 @@ export function createPublishBitbucketAction(options: { token?: string | undefined; }>; -// Warning: (ae-missing-release-tag) "createPublishFileAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function createPublishFileAction(): TemplateAction<{ path: string; }>; -// Warning: (ae-missing-release-tag) "createPublishGithubAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function createPublishGithubAction(options: { integrations: ScmIntegrationRegistry; config: Config; @@ -252,10 +246,7 @@ export function createPublishGithubAction(options: { topics?: string[] | undefined; }>; -// Warning: (ae-forgotten-export) The symbol "CreateGithubPullRequestActionOptions" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "createPublishGithubPullRequestAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const createPublishGithubPullRequestAction: ({ integrations, githubCredentialsProvider, @@ -270,9 +261,7 @@ export const createPublishGithubPullRequestAction: ({ token?: string | undefined; }>; -// Warning: (ae-missing-release-tag) "createPublishGitlabAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function createPublishGitlabAction(options: { integrations: ScmIntegrationRegistry; config: Config; @@ -284,9 +273,7 @@ export function createPublishGitlabAction(options: { token?: string | undefined; }>; -// Warning: (ae-missing-release-tag) "createPublishGitlabMergeRequestAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const createPublishGitlabMergeRequestAction: (options: { integrations: ScmIntegrationRegistry; }) => TemplateAction<{ @@ -299,14 +286,10 @@ export const createPublishGitlabMergeRequestAction: (options: { token?: string | undefined; }>; -// Warning: (ae-missing-release-tag) "createRouter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function createRouter(options: RouterOptions): Promise; -// Warning: (ae-missing-release-tag) "createTemplateAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const createTemplateAction: ( templateAction: TemplateAction, ) => TemplateAction; @@ -345,8 +328,6 @@ export class DatabaseTaskStore implements TaskStore { status: TaskStatus; eventBody: JsonObject; }): Promise; - // Warning: (ae-forgotten-export) The symbol "DatabaseTaskStoreOptions" needs to be exported by the entry point index.d.ts - // // (undocumented) static create(options: DatabaseTaskStoreOptions): Promise; // (undocumented) @@ -377,11 +358,14 @@ export class DatabaseTaskStore implements TaskStore { }>; } +// @public +export type DatabaseTaskStoreOptions = { + database: Knex; +}; + // @public @deprecated export type DispatchResult = TaskBrokerDispatchResult; -// Warning: (ae-forgotten-export) The symbol "RunCommandOptions" needs to be exported by the entry point index.d.ts -// // @public export const executeShellCommand: (options: RunCommandOptions) => Promise; @@ -419,6 +403,16 @@ export class OctokitProvider { ): Promise; } +// @public (undocumented) +export interface OctokitWithPullRequestPluginClient { + // (undocumented) + createPullRequest(options: createPullRequest.Options): Promise<{ + data: { + html_url: string; + }; + } | null>; +} + // @public export interface RouterOptions { // (undocumented) @@ -446,6 +440,14 @@ export interface RouterOptions { // @public @deprecated export const runCommand: (options: RunCommandOptions) => Promise; +// @public (undocumented) +export type RunCommandOptions = { + command: string; + args: string[]; + options?: SpawnOptionsWithoutStdio; + logStream?: Writable; +}; + // @public (undocumented) export class ScaffolderEntitiesProcessor implements CatalogProcessor { // (undocumented) @@ -636,8 +638,6 @@ export class TaskWorker { start(): void; } -// Warning: (ae-missing-release-tag) "TemplateAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type TemplateAction = { id: string; @@ -649,9 +649,7 @@ export type TemplateAction = { handler: (ctx: ActionContext) => Promise; }; -// Warning: (ae-missing-release-tag) "TemplateActionRegistry" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class TemplateActionRegistry { // (undocumented) get(actionId: string): TemplateAction; @@ -661,8 +659,6 @@ export class TemplateActionRegistry { register(action: TemplateAction): void; } -// Warning: (ae-missing-release-tag) "TemplateFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type TemplateFilter = (...args: JsonValue[]) => JsonValue | undefined; ``` diff --git a/plugins/scaffolder-backend/src/lib/templating/SecureTemplater.ts b/plugins/scaffolder-backend/src/lib/templating/SecureTemplater.ts index 6d3ce6f556..e82620a90d 100644 --- a/plugins/scaffolder-backend/src/lib/templating/SecureTemplater.ts +++ b/plugins/scaffolder-backend/src/lib/templating/SecureTemplater.ts @@ -95,6 +95,7 @@ const { render, renderCompat } = (() => { })(); `; +/** @public */ export type TemplateFilter = (...args: JsonValue[]) => JsonValue | undefined; export interface SecureTemplaterOptions { diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/TemplateActionRegistry.ts b/plugins/scaffolder-backend/src/scaffolder/actions/TemplateActionRegistry.ts index e546d5bf9a..8a2a00d121 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/TemplateActionRegistry.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/TemplateActionRegistry.ts @@ -18,6 +18,10 @@ import { JsonObject } from '@backstage/types'; import { ConflictError, NotFoundError } from '@backstage/errors'; import { TemplateAction } from './types'; +/** + * Registry of all registered template actions. + * @public + */ export class TemplateActionRegistry { private readonly actions = new Map>(); diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/catalog/register.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/catalog/register.ts index 65d0e1b1e7..1b30268d9d 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/catalog/register.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/catalog/register.ts @@ -20,6 +20,10 @@ import { CatalogApi } from '@backstage/catalog-client'; import { stringifyEntityRef } from '@backstage/catalog-model'; import { createTemplateAction } from '../../createTemplateAction'; +/** + * Registers entities from a catalog descriptor file in the workspace into the software catalog. + * @public + */ export function createCatalogRegisterAction(options: { catalogClient: CatalogApi; integrations: ScmIntegrations; diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/catalog/write.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/catalog/write.ts index 9b159f1611..b55e521784 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/catalog/write.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/catalog/write.ts @@ -20,6 +20,10 @@ import * as yaml from 'yaml'; import { Entity } from '@backstage/catalog-model'; import { resolveSafeChildPath } from '@backstage/backend-common'; +/** + * Writes a catalog descriptor file containing the provided entity to a path in the workspace. + * @public + */ export function createCatalogWriteAction() { return createTemplateAction<{ filePath?: string; entity: Entity }>({ id: 'catalog:write', diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts index 36ea842a66..59d4c333c6 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/debug/log.ts @@ -19,8 +19,14 @@ import { relative, join } from 'path'; import { createTemplateAction } from '../../createTemplateAction'; /** + * Writes a message into the log or lists all files in the workspace + * + * @remarks + * * This task is useful for local development and testing of both the scaffolder * and scaffolder templates. + * + * @public */ export function createDebugLogAction() { return createTemplateAction<{ message?: string; listWorkspace?: boolean }>({ diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/plain.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/plain.ts index 17f49a5bd4..6dbe08f61b 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/plain.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/plain.ts @@ -19,6 +19,11 @@ import { ScmIntegrations } from '@backstage/integration'; import { fetchContents } from './helpers'; import { createTemplateAction } from '../../createTemplateAction'; +/** + * Downloads content and places it in the workspace, or optionally + * in a subdirectory specified by the 'targetPath' input option. + * @public + */ export function createFetchPlainAction(options: { reader: UrlReader; integrations: ScmIntegrations; diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/template.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/template.ts index a8ba9ac19f..3d3d319c57 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/template.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/template.ts @@ -28,6 +28,13 @@ import { SecureTemplater, } from '../../../../lib/templating/SecureTemplater'; +/** + * Downloads a skeleton, templates variables into file and directory names and content. + * Then places the result in the workspace, or optionally in a subdirectory + * specified by the 'targetPath' input option. + * + * @public + */ export function createFetchTemplateAction(options: { reader: UrlReader; integrations: ScmIntegrations; diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/filesystem/delete.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/filesystem/delete.ts index 068f777ec5..bf2953e75a 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/filesystem/delete.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/filesystem/delete.ts @@ -18,6 +18,10 @@ import { InputError } from '@backstage/errors'; import { resolveSafeChildPath } from '@backstage/backend-common'; import fs from 'fs-extra'; +/** + * Creates new action that enables deletion of files and directories in the workspace. + * @public + */ export const createFilesystemDeleteAction = () => { return createTemplateAction<{ files: string[] }>({ id: 'fs:delete', diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/filesystem/rename.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/filesystem/rename.ts index c3e128cec5..7c8dad7559 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/filesystem/rename.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/filesystem/rename.ts @@ -19,6 +19,10 @@ import { resolveSafeChildPath } from '@backstage/backend-common'; import { InputError } from '@backstage/errors'; import fs from 'fs-extra'; +/** + * Creates a new action that allows renames of files and directories in the workspace. + * @public + */ export const createFilesystemRenameAction = () => { return createTemplateAction<{ files: Array<{ diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/githubActionsDispatch.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/githubActionsDispatch.ts index f2329c9ca1..b9d77559e0 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/githubActionsDispatch.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/githubActionsDispatch.ts @@ -23,6 +23,10 @@ import { createTemplateAction } from '../../createTemplateAction'; import { parseRepoUrl } from '../publish/util'; import { getOctokitOptions } from './helpers'; +/** + * Creates a new action that dispatches a GitHub Action workflow for a given branch or tag. + * @public + */ export function createGithubActionsDispatchAction(options: { integrations: ScmIntegrations; githubCredentialsProvider?: GithubCredentialsProvider; diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/githubWebhook.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/githubWebhook.ts index e2cf744845..4547ce4492 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/githubWebhook.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/githubWebhook.ts @@ -24,6 +24,10 @@ import { Octokit } from 'octokit'; import { getOctokitOptions } from './helpers'; import { parseRepoUrl } from '../publish/util'; +/** + * Creates new action that creates a webhook for a repository on GitHub. + * @public + */ export function createGithubWebhookAction(options: { integrations: ScmIntegrationRegistry; defaultWebhookSecret?: string; diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/helpers.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/helpers.ts index 7ee334a3f7..79537ff8dc 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/helpers.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/helpers.ts @@ -21,6 +21,7 @@ import { Git } from '@backstage/backend-common'; import { Octokit } from 'octokit'; import { assertError } from '@backstage/errors'; +/** @public */ export type RunCommandOptions = { /** command to run */ command: string; diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/index.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/index.ts index 8930c23126..8be1b62eaa 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/index.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/index.ts @@ -26,3 +26,4 @@ export * from './github'; export { createFetchCookiecutterAction } from '@backstage/plugin-scaffolder-backend-module-cookiecutter'; export { runCommand, executeShellCommand } from './helpers'; +export type { RunCommandOptions } from './helpers'; diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/azure.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/azure.ts index 4f67a0e45f..7a8e963b5c 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/azure.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/azure.ts @@ -23,6 +23,11 @@ import { getRepoSourceDirectory, parseRepoUrl } from './util'; import { createTemplateAction } from '../../createTemplateAction'; import { Config } from '@backstage/config'; +/** + * Creates a new action that initializes a git repository of the content in the workspace + * and publishes it to Azure. + * @public + */ export function createPublishAzureAction(options: { integrations: ScmIntegrationRegistry; config: Config; diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/bitbucket.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/bitbucket.ts index 47ebce0550..6383275754 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/bitbucket.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/bitbucket.ts @@ -192,6 +192,11 @@ const performEnableLFS = async (opts: { ); }; +/** + * Creates a new action that initializes a git repository of the content in the workspace + * and publishes it to Bitbucket. + * @public + */ export function createPublishBitbucketAction(options: { integrations: ScmIntegrationRegistry; config: Config; diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/file.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/file.ts index d59c87d4fa..2d2cb85930 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/file.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/file.ts @@ -23,8 +23,12 @@ import { createTemplateAction } from '../../createTemplateAction'; * This task is useful for local development and testing of both the scaffolder * and scaffolder templates. * + * @remarks + * * This action is not installed by default and should not be installed in * production, as it writes the files to the local filesystem of the scaffolder. + * + * @public */ export function createPublishFileAction() { return createTemplateAction<{ path: string }>({ diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/github.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/github.ts index 37e2ffb7d3..926a63915a 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/github.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/github.ts @@ -28,6 +28,12 @@ import { assertError, InputError } from '@backstage/errors'; import { getOctokitOptions } from '../github/helpers'; import { Octokit } from 'octokit'; +/** + * Creates a new action that initializes a git repository of the content in the workspace + * and publishes it to GitHub. + * + * @public + */ export function createPublishGithubAction(options: { integrations: ScmIntegrationRegistry; config: Config; diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.test.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.test.ts index 64d3bc41de..9956f16003 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.test.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.test.ts @@ -26,9 +26,9 @@ import { resolve as resolvePath } from 'path'; import { Writable } from 'stream'; import { ActionContext, TemplateAction } from '../../types'; import { - ClientFactoryInput, + CreateGithubPullRequestClientFactoryInput, createPublishGithubPullRequestAction, - PullRequestCreator, + OctokitWithPullRequestPluginClient, } from './githubPullRequest'; const root = os.platform() === 'win32' ? 'C:\\root' : '/root'; @@ -42,9 +42,11 @@ type GithubPullRequestActionInput = ReturnType< describe('createPublishGithubPullRequestAction', () => { let instance: TemplateAction; - let fakeClient: PullRequestCreator; + let fakeClient: OctokitWithPullRequestPluginClient; - let clientFactory: (input: ClientFactoryInput) => Promise; + let clientFactory: ( + input: CreateGithubPullRequestClientFactoryInput, + ) => Promise; beforeEach(() => { const integrations = ScmIntegrations.fromConfig(new ConfigReader({})); diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts index 110c865fc6..750781206d 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts @@ -34,21 +34,15 @@ export type Encoding = 'utf-8' | 'base64'; class GithubResponseError extends CustomErrorBase {} -type CreatePullRequestResponse = { - data: { html_url: string }; -}; - -export interface PullRequestCreator { - createPullRequest( - options: createPullRequest.Options, - ): Promise; +/** @public */ +export interface OctokitWithPullRequestPluginClient { + createPullRequest(options: createPullRequest.Options): Promise<{ + data: { html_url: string }; + } | null>; } -export type PullRequestCreatorConstructor = ( - octokit: Octokit, -) => PullRequestCreator; - -export type ClientFactoryInput = { +/** @public */ +export type CreateGithubPullRequestClientFactoryInput = { integrations: ScmIntegrationRegistry; githubCredentialsProvider?: GithubCredentialsProvider; host: string; @@ -64,7 +58,7 @@ export const defaultClientFactory = async ({ repo, host = 'github.com', token: providedToken, -}: ClientFactoryInput): Promise => { +}: CreateGithubPullRequestClientFactoryInput): Promise => { const [encodedHost, encodedOwner, encodedRepo] = [host, owner, repo].map( encodeURIComponent, ); @@ -80,12 +74,19 @@ export const defaultClientFactory = async ({ return new OctokitPR(octokitOptions); }; -interface CreateGithubPullRequestActionOptions { +/** @public */ +export interface CreateGithubPullRequestActionOptions { integrations: ScmIntegrationRegistry; githubCredentialsProvider?: GithubCredentialsProvider; - clientFactory?: (input: ClientFactoryInput) => Promise; + clientFactory?: ( + input: CreateGithubPullRequestClientFactoryInput, + ) => Promise; } +/** + * Creates a Github Pull Request action. + * @public + */ export const createPublishGithubPullRequestAction = ({ integrations, githubCredentialsProvider, diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/gitlab.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/gitlab.ts index a3c1919b63..9aa12803eb 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/gitlab.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/gitlab.ts @@ -22,6 +22,12 @@ import { getRepoSourceDirectory, parseRepoUrl } from './util'; import { createTemplateAction } from '../../createTemplateAction'; import { Config } from '@backstage/config'; +/** + * Creates a new action that initializes a git repository of the content in the workspace + * and publishes it to GitLab. + * + * @public + */ export function createPublishGitlabAction(options: { integrations: ScmIntegrationRegistry; config: Config; diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/gitlabMergeRequest.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/gitlabMergeRequest.ts index e04eb5cdb5..63cfeaa8b3 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/gitlabMergeRequest.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/gitlabMergeRequest.ts @@ -24,6 +24,11 @@ import { InputError } from '@backstage/errors'; import { parseRepoUrl } from './util'; import { resolveSafeChildPath } from '@backstage/backend-common'; +/** + * Create a new action that creates a gitlab merge request. + * + * @public + */ export const createPublishGitlabMergeRequestAction = (options: { integrations: ScmIntegrationRegistry; }) => { diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/index.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/index.ts index c42b04e55e..7d85b45edd 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/index.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/index.ts @@ -19,5 +19,10 @@ export { createPublishBitbucketAction } from './bitbucket'; export { createPublishFileAction } from './file'; export { createPublishGithubAction } from './github'; export { createPublishGithubPullRequestAction } from './githubPullRequest'; +export type { + CreateGithubPullRequestClientFactoryInput, + CreateGithubPullRequestActionOptions, + OctokitWithPullRequestPluginClient, +} from './githubPullRequest'; export { createPublishGitlabAction } from './gitlab'; export { createPublishGitlabMergeRequestAction } from './gitlabMergeRequest'; diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/createTemplateAction.ts b/plugins/scaffolder-backend/src/scaffolder/actions/createTemplateAction.ts index 243f39e070..8893fa0f20 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/createTemplateAction.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/createTemplateAction.ts @@ -17,6 +17,10 @@ import { JsonObject } from '@backstage/types'; import { TemplateAction } from './types'; +/** + * This function is used to create new template actions to get type safety. + * @public + */ export const createTemplateAction = ( templateAction: TemplateAction, ): TemplateAction => { diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/types.ts b/plugins/scaffolder-backend/src/scaffolder/actions/types.ts index 1aa4f81bdd..2a87f58fd8 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/types.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/types.ts @@ -24,6 +24,9 @@ import { TemplateMetadata, } from '@backstage/plugin-scaffolder-common'; +/** + * ActionContext is passed into scaffolder actions. + * @public */ export type ActionContext = { /** * Base URL for the location of the task spec, typically the url of the source entity file. @@ -50,6 +53,7 @@ export type ActionContext = { templateInfo?: TemplateInfo; }; +/** @public */ export type TemplateAction = { id: string; description?: string; diff --git a/plugins/scaffolder-backend/src/scaffolder/tasks/index.ts b/plugins/scaffolder-backend/src/scaffolder/tasks/index.ts index a2bf5f0e1c..b108a3308d 100644 --- a/plugins/scaffolder-backend/src/scaffolder/tasks/index.ts +++ b/plugins/scaffolder-backend/src/scaffolder/tasks/index.ts @@ -14,6 +14,7 @@ * limitations under the License. */ export { DatabaseTaskStore } from './DatabaseTaskStore'; +export type { DatabaseTaskStoreOptions } from './DatabaseTaskStore'; export { TaskManager } from './StorageTaskBroker'; export type { CurrentClaimedTask, TaskState } from './StorageTaskBroker'; export { TaskWorker } from './TaskWorker'; diff --git a/plugins/scaffolder-backend/src/service/router.ts b/plugins/scaffolder-backend/src/service/router.ts index 84febe4225..8f793a34d8 100644 --- a/plugins/scaffolder-backend/src/service/router.ts +++ b/plugins/scaffolder-backend/src/service/router.ts @@ -75,6 +75,7 @@ function isSupportedTemplate( ); } +/** @public */ export async function createRouter( options: RouterOptions, ): Promise {