diff --git a/packages/backend-common/api-report-testUtils.md b/packages/backend-common/api-report-testUtils.md index 9dbdade10e..d53748234e 100644 --- a/packages/backend-common/api-report-testUtils.md +++ b/packages/backend-common/api-report-testUtils.md @@ -3,24 +3,19 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts -// @public -export function overridePackagePathResolution( - options: OverridePackagePathResolutionOptions, -): PackagePathResolutionOverride; +import { overridePackagePathResolution as overridePackagePathResolution_2 } from '@backstage/backend-plugin-api/testUtils'; +import { OverridePackagePathResolutionOptions as OverridePackagePathResolutionOptions_2 } from '@backstage/backend-plugin-api/testUtils'; +import { PackagePathResolutionOverride as PackagePathResolutionOverride_2 } from '@backstage/backend-plugin-api/testUtils'; -// @public (undocumented) -export interface OverridePackagePathResolutionOptions { - packageName: string; - path?: string; - paths?: { - [path in string]: string | (() => string); - }; -} +// @public @deprecated (undocumented) +export const overridePackagePathResolution: typeof overridePackagePathResolution_2; -// @public (undocumented) -export interface PackagePathResolutionOverride { - restore(): void; -} +// @public @deprecated (undocumented) +export type OverridePackagePathResolutionOptions = + OverridePackagePathResolutionOptions_2; + +// @public @deprecated (undocumented) +export type PackagePathResolutionOverride = PackagePathResolutionOverride_2; // (No @packageDocumentation comment for this package) ``` diff --git a/packages/backend-common/src/deprecated.ts b/packages/backend-common/src/deprecated.ts new file mode 100644 index 0000000000..397d97f20e --- /dev/null +++ b/packages/backend-common/src/deprecated.ts @@ -0,0 +1,43 @@ +/* + * Copyright 2024 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { + overridePackagePathResolution as _overridePackagePathResolution, + OverridePackagePathResolutionOptions as _OverridePackagePathResolutionOptions, + PackagePathResolutionOverride as _PackagePathResolutionOverride, +} from '@backstage/backend-plugin-api/testUtils'; + +/** + * @public + * @deprecated This function is deprecated and will be removed in future release, see https://github.com/backstage/backstage/issues/24493. + * Please use the `overridePackagePathResolution` function from the `@backstage/backend-plugin-api/testUtils` package instead. + */ +export const overridePackagePathResolution = _overridePackagePathResolution; + +/** + * @public + * @deprecated This type is deprecated and will be removed in a future release, see https://github.com/backstage/backstage/issues/24493. + * Please use the `OverridePackagePathResolutionOptions` type from the `@backstage/backend-plugin-api/testUtils` package instead. + */ +export type OverridePackagePathResolutionOptions = + _OverridePackagePathResolutionOptions; + +/** + * @public + * @deprecated This type is deprecated and will be removed in a future release, see https://github.com/backstage/backstage/issues/24493. + * Please use the `PackagePathResolutionOverride` type from the `@backstage/backend-plugin-api/testUtils` package instead. + */ +export type PackagePathResolutionOverride = _PackagePathResolutionOverride; diff --git a/packages/backend-common/src/testUtils.ts b/packages/backend-common/src/testUtils.ts index 9616ab1701..bae633428f 100644 --- a/packages/backend-common/src/testUtils.ts +++ b/packages/backend-common/src/testUtils.ts @@ -1,5 +1,5 @@ /* - * Copyright 2023 The Backstage Authors + * Copyright 2024 The Backstage Authors * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -14,66 +14,8 @@ * limitations under the License. */ -import { packagePathMocks } from './paths'; -import { posix as posixPath, resolve as resolvePath } from 'path'; - -/** @public */ -export interface PackagePathResolutionOverride { - /** Restores the normal behavior of resolvePackagePath */ - restore(): void; -} - -/** @public */ -export interface OverridePackagePathResolutionOptions { - /** The name of the package to mock the resolved path of */ - packageName: string; - - /** A replacement for the root package path */ - path?: string; - - /** - * Replacements for package sub-paths, each key must be an exact match of the posix-style path - * that is being resolved within the package. - * - * For example, code calling `resolvePackagePath('x', 'foo', 'bar')` would match only the following - * configuration: `overridePackagePathResolution({ packageName: 'x', paths: { 'foo/bar': baz } })` - */ - paths?: { [path in string]: string | (() => string) }; -} - -/** - * This utility helps you override the paths returned by `resolvePackagePath` for a given package. - * - * @public - */ -export function overridePackagePathResolution( - options: OverridePackagePathResolutionOptions, -): PackagePathResolutionOverride { - const name = options.packageName; - - if (packagePathMocks.has(name)) { - throw new Error( - `Tried to override resolution for '${name}' more than once for package '${name}'`, - ); - } - - packagePathMocks.set(name, paths => { - const joinedPath = posixPath.join(...paths); - const localResolver = options.paths?.[joinedPath]; - if (localResolver) { - return typeof localResolver === 'function' - ? localResolver() - : localResolver; - } - if (options.path) { - return resolvePath(options.path, ...paths); - } - return undefined; - }); - - return { - restore() { - packagePathMocks.delete(name); - }, - }; -} +export { + overridePackagePathResolution, + type OverridePackagePathResolutionOptions, + type PackagePathResolutionOverride, +} from './deprecated'; diff --git a/packages/backend-plugin-api/api-report-testUtils.md b/packages/backend-plugin-api/api-report-testUtils.md new file mode 100644 index 0000000000..8c9bba8398 --- /dev/null +++ b/packages/backend-plugin-api/api-report-testUtils.md @@ -0,0 +1,26 @@ +## API Report File for "@backstage/backend-plugin-api" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts +// @public +export function overridePackagePathResolution( + options: OverridePackagePathResolutionOptions, +): PackagePathResolutionOverride; + +// @public (undocumented) +export interface OverridePackagePathResolutionOptions { + packageName: string; + path?: string; + paths?: { + [path in string]: string | (() => string); + }; +} + +// @public (undocumented) +export interface PackagePathResolutionOverride { + restore(): void; +} + +// (No @packageDocumentation comment for this package) +``` diff --git a/packages/backend-plugin-api/package.json b/packages/backend-plugin-api/package.json index fff99c0370..c83ef854b8 100644 --- a/packages/backend-plugin-api/package.json +++ b/packages/backend-plugin-api/package.json @@ -21,6 +21,7 @@ "exports": { ".": "./src/index.ts", "./alpha": "./src/alpha.ts", + "./testUtils": "./src/testUtils.ts", "./package.json": "./package.json" }, "main": "src/index.ts", @@ -30,6 +31,9 @@ "alpha": [ "src/alpha.ts" ], + "testUtils": [ + "src/testUtils.ts" + ], "package.json": [ "package.json" ] diff --git a/packages/backend-plugin-api/src/testUtils.ts b/packages/backend-plugin-api/src/testUtils.ts new file mode 100644 index 0000000000..a04cae4c25 --- /dev/null +++ b/packages/backend-plugin-api/src/testUtils.ts @@ -0,0 +1,81 @@ +/* + * Copyright 2023 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +// TODO: Remove this relative import when extrating the path utilities to this package +// eslint-disable-next-line @backstage/no-relative-monorepo-imports +import { packagePathMocks } from '../../backend-common/src/paths'; +import { posix as posixPath, resolve as resolvePath } from 'path'; + +/** @public */ +export interface PackagePathResolutionOverride { + /** Restores the normal behavior of resolvePackagePath */ + restore(): void; +} + +/** @public */ +export interface OverridePackagePathResolutionOptions { + /** The name of the package to mock the resolved path of */ + packageName: string; + + /** A replacement for the root package path */ + path?: string; + + /** + * Replacements for package sub-paths, each key must be an exact match of the posix-style path + * that is being resolved within the package. + * + * For example, code calling `resolvePackagePath('x', 'foo', 'bar')` would match only the following + * configuration: `overridePackagePathResolution({ packageName: 'x', paths: { 'foo/bar': baz } })` + */ + paths?: { [path in string]: string | (() => string) }; +} + +/** + * This utility helps you override the paths returned by `resolvePackagePath` for a given package. + * + * @public + */ +export function overridePackagePathResolution( + options: OverridePackagePathResolutionOptions, +): PackagePathResolutionOverride { + const name = options.packageName; + + if (packagePathMocks.has(name)) { + throw new Error( + `Tried to override resolution for '${name}' more than once for package '${name}'`, + ); + } + + packagePathMocks.set(name, paths => { + const joinedPath = posixPath.join(...paths); + const localResolver = options.paths?.[joinedPath]; + if (localResolver) { + return typeof localResolver === 'function' + ? localResolver() + : localResolver; + } + if (options.path) { + return resolvePath(options.path, ...paths); + } + return undefined; + }); + + return { + restore() { + packagePathMocks.delete(name); + }, + }; +} diff --git a/plugins/app-backend/src/service/appPlugin.test.ts b/plugins/app-backend/src/service/appPlugin.test.ts index 647697c204..c239d476bd 100644 --- a/plugins/app-backend/src/service/appPlugin.test.ts +++ b/plugins/app-backend/src/service/appPlugin.test.ts @@ -22,7 +22,7 @@ import { } from '@backstage/backend-test-utils'; import { appPlugin } from './appPlugin'; import { createRootLogger } from '@backstage/backend-common'; -import { overridePackagePathResolution } from '@backstage/backend-common/testUtils'; +import { overridePackagePathResolution } from '@backstage/backend-plugin-api/testUtils'; const mockDir = createMockDirectory(); overridePackagePathResolution({ diff --git a/plugins/techdocs-node/src/stages/publish/local.test.ts b/plugins/techdocs-node/src/stages/publish/local.test.ts index 4019f80d11..89a38c7ed2 100644 --- a/plugins/techdocs-node/src/stages/publish/local.test.ts +++ b/plugins/techdocs-node/src/stages/publish/local.test.ts @@ -17,7 +17,7 @@ import { getVoidLogger, PluginEndpointDiscovery, } from '@backstage/backend-common'; -import { overridePackagePathResolution } from '@backstage/backend-common/testUtils'; +import { overridePackagePathResolution } from '@backstage/backend-plugin-api/testUtils'; import { ConfigReader } from '@backstage/config'; import express from 'express'; import request from 'supertest';