From 9cf05fef7c73750c8fcd914b66f27fa821ac7381 Mon Sep 17 00:00:00 2001 From: Tyler Butler Date: Sat, 19 Oct 2024 17:19:15 -0700 Subject: [PATCH 1/5] init package --- _repoLayout.config.cjs | 207 +++++ build-tools/package.json | 2 +- .../test/commands/test-only-filter.test.ts | 4 +- .../build-cli/src/test/filter.test.ts | 15 +- .../build-infrastructure/.eslintrc.cjs | 38 + .../packages/build-infrastructure/.gitignore | 11 + .../build-infrastructure/.mocharc.json | 7 + .../packages/build-infrastructure/.npmignore | 14 + .../build-infrastructure/.prettierignore | 3 + .../packages/build-infrastructure/LICENSE | 21 + .../packages/build-infrastructure/README.md | 239 ++++++ .../build-infrastructure/api-extractor.json | 5 + .../build-infrastructure/api-markdown.mjs | 25 + .../api-report/build-infrastructure.api.md | 196 +++++ .../packages/build-infrastructure/bin/dev.cmd | 3 + .../packages/build-infrastructure/bin/dev.mjs | 9 + .../packages/build-infrastructure/bin/run.cmd | 3 + .../packages/build-infrastructure/bin/run.mjs | 9 + .../packages/build-infrastructure/biome.jsonc | 7 + .../build-infrastructure/docs/README.md | 293 +++++++ .../docs/classes/NotInGitRepository.md | 173 ++++ .../docs/functions/getFluidRepoLayout.md | 49 ++ .../docs/functions/isIPackage.md | 25 + .../docs/functions/isIReleaseGroup.md | 25 + .../docs/interfaces/FluidPackageJsonFields.md | 29 + .../docs/interfaces/IFluidBuildDir.md | 27 + .../docs/interfaces/IFluidBuildDirs.md | 15 + .../docs/interfaces/IFluidRepo.md | 220 +++++ .../docs/interfaces/IFluidRepoLayout.md | 67 ++ .../docs/interfaces/IPackage.md | 336 ++++++++ .../docs/interfaces/IPackageManager.md | 53 ++ .../docs/interfaces/IReleaseGroup.md | 608 ++++++++++++++ .../docs/interfaces/IWorkspace.md | 645 +++++++++++++++ .../docs/interfaces/Installable.md | 58 ++ .../docs/interfaces/PackageDependency.md | 45 + .../docs/interfaces/ReleaseGroupDefinition.md | 72 ++ .../docs/interfaces/Reloadable.md | 32 + .../docs/interfaces/WorkspaceDefinition.md | 35 + .../type-aliases/AdditionalPackageProps.md | 15 + .../docs/type-aliases/IFluidBuildDirEntry.md | 19 + .../docs/type-aliases/PackageJson.md | 15 + .../docs/type-aliases/PackageManagerName.md | 17 + .../docs/type-aliases/PackageName.md | 17 + .../docs/type-aliases/ReleaseGroupName.md | 17 + .../docs/type-aliases/WorkspaceName.md | 17 + .../variables/FLUIDREPO_CONFIG_VERSION.md | 17 + .../mocha-multi-reporter-config.json | 6 + .../build-infrastructure/package.json | 126 +++ .../build-infrastructure/src/config.ts | 220 +++++ .../build-infrastructure/src/errors.ts | 13 + .../build-infrastructure/src/index.ts | 69 ++ .../test/data/testRepo/.changeset/README.md | 11 + .../.changeset/bump-main-group-minor.md | 5 + .../test/data/testRepo/.changeset/config.json | 34 + .../test/data/testRepo/fluidBuild.config.cjs | 61 ++ .../src/test/data/testRepo/package.json | 20 + .../packages/group2/pkg-d/package.json | 16 + .../packages/group2/pkg-e/package.json | 14 + .../packages/group3/pkg-f/package.json | 17 + .../packages/group3/pkg-f/src/index.mjs | 1 + .../packages/group3/pkg-g/package.json | 13 + .../data/testRepo/packages/pkg-a/package.json | 17 + .../data/testRepo/packages/pkg-b/package.json | 16 + .../data/testRepo/packages/pkg-c/package.json | 17 + .../testRepo/packages/shared/package.json | 17 + .../src/test/data/testRepo/pnpm-lock.yaml | 766 +++++++++++++++++ .../test/data/testRepo/pnpm-workspace.yaml | 2 + .../test/data/testRepo/second/package.json | 16 + .../second/packages/other-pkg-a/package.json | 16 + .../second/packages/other-pkg-b/package.json | 13 + .../test/data/testRepo/second/pnpm-lock.yaml | 21 + .../data/testRepo/second/pnpm-workspace.yaml | 2 + .../build-infrastructure/src/test/dirname.cts | 14 + .../build-infrastructure/src/test/init.ts | 20 + .../src/test/tsconfig.cjs.json | 12 + .../src/test/tsconfig.json | 14 + .../build-infrastructure/src/types.ts | 384 +++++++++ .../build-infrastructure/tsconfig.cjs.json | 7 + .../build-infrastructure/tsconfig.json | 12 + .../build-infrastructure/typedoc.config.cjs | 30 + build-tools/pnpm-lock.yaml | 778 +++++++++++++++++- fluidBuild.config.cjs | 12 + 82 files changed, 6554 insertions(+), 17 deletions(-) create mode 100644 _repoLayout.config.cjs create mode 100644 build-tools/packages/build-infrastructure/.eslintrc.cjs create mode 100644 build-tools/packages/build-infrastructure/.gitignore create mode 100644 build-tools/packages/build-infrastructure/.mocharc.json create mode 100644 build-tools/packages/build-infrastructure/.npmignore create mode 100644 build-tools/packages/build-infrastructure/.prettierignore create mode 100644 build-tools/packages/build-infrastructure/LICENSE create mode 100644 build-tools/packages/build-infrastructure/README.md create mode 100644 build-tools/packages/build-infrastructure/api-extractor.json create mode 100644 build-tools/packages/build-infrastructure/api-markdown.mjs create mode 100644 build-tools/packages/build-infrastructure/api-report/build-infrastructure.api.md create mode 100644 build-tools/packages/build-infrastructure/bin/dev.cmd create mode 100755 build-tools/packages/build-infrastructure/bin/dev.mjs create mode 100644 build-tools/packages/build-infrastructure/bin/run.cmd create mode 100755 build-tools/packages/build-infrastructure/bin/run.mjs create mode 100644 build-tools/packages/build-infrastructure/biome.jsonc create mode 100644 build-tools/packages/build-infrastructure/docs/README.md create mode 100644 build-tools/packages/build-infrastructure/docs/classes/NotInGitRepository.md create mode 100644 build-tools/packages/build-infrastructure/docs/functions/getFluidRepoLayout.md create mode 100644 build-tools/packages/build-infrastructure/docs/functions/isIPackage.md create mode 100644 build-tools/packages/build-infrastructure/docs/functions/isIReleaseGroup.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/FluidPackageJsonFields.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/IFluidBuildDir.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/IFluidBuildDirs.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/IFluidRepo.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/IFluidRepoLayout.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/IPackage.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/IPackageManager.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/IReleaseGroup.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/IWorkspace.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/Installable.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/PackageDependency.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/ReleaseGroupDefinition.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/Reloadable.md create mode 100644 build-tools/packages/build-infrastructure/docs/interfaces/WorkspaceDefinition.md create mode 100644 build-tools/packages/build-infrastructure/docs/type-aliases/AdditionalPackageProps.md create mode 100644 build-tools/packages/build-infrastructure/docs/type-aliases/IFluidBuildDirEntry.md create mode 100644 build-tools/packages/build-infrastructure/docs/type-aliases/PackageJson.md create mode 100644 build-tools/packages/build-infrastructure/docs/type-aliases/PackageManagerName.md create mode 100644 build-tools/packages/build-infrastructure/docs/type-aliases/PackageName.md create mode 100644 build-tools/packages/build-infrastructure/docs/type-aliases/ReleaseGroupName.md create mode 100644 build-tools/packages/build-infrastructure/docs/type-aliases/WorkspaceName.md create mode 100644 build-tools/packages/build-infrastructure/docs/variables/FLUIDREPO_CONFIG_VERSION.md create mode 100644 build-tools/packages/build-infrastructure/mocha-multi-reporter-config.json create mode 100644 build-tools/packages/build-infrastructure/package.json create mode 100644 build-tools/packages/build-infrastructure/src/config.ts create mode 100644 build-tools/packages/build-infrastructure/src/errors.ts create mode 100644 build-tools/packages/build-infrastructure/src/index.ts create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/.changeset/README.md create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/.changeset/bump-main-group-minor.md create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/.changeset/config.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/fluidBuild.config.cjs create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/package.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group2/pkg-d/package.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group2/pkg-e/package.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-f/package.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-f/src/index.mjs create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-g/package.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-a/package.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-b/package.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-c/package.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/shared/package.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/pnpm-lock.yaml create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/pnpm-workspace.yaml create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/second/package.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/second/packages/other-pkg-a/package.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/second/packages/other-pkg-b/package.json create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/second/pnpm-lock.yaml create mode 100644 build-tools/packages/build-infrastructure/src/test/data/testRepo/second/pnpm-workspace.yaml create mode 100644 build-tools/packages/build-infrastructure/src/test/dirname.cts create mode 100644 build-tools/packages/build-infrastructure/src/test/init.ts create mode 100644 build-tools/packages/build-infrastructure/src/test/tsconfig.cjs.json create mode 100644 build-tools/packages/build-infrastructure/src/test/tsconfig.json create mode 100644 build-tools/packages/build-infrastructure/src/types.ts create mode 100644 build-tools/packages/build-infrastructure/tsconfig.cjs.json create mode 100644 build-tools/packages/build-infrastructure/tsconfig.json create mode 100644 build-tools/packages/build-infrastructure/typedoc.config.cjs diff --git a/_repoLayout.config.cjs b/_repoLayout.config.cjs new file mode 100644 index 000000000000..3b521bb44787 --- /dev/null +++ b/_repoLayout.config.cjs @@ -0,0 +1,207 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +/** + * This file will be renamed to repoLayout.config.cjs in a future change. Right now it is an example of what the + * IFluidRepoLayout config would look like for our main FluidFramework repo. + */ + +// Enable TypeScript type-checking for this file. +// See https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#ts-check +// @ts-check + +/** + * All fluid scopes EXCEPT for @fluid-example + */ +const fluidScopes = [ + "@fluidframework", + "@fluid-experimental", + "@fluid-internal", + "@fluid-private", + "@fluid-tools", +]; + +/** + * The settings in this file configure the repo layout used by build-tools, such as fluid-build and flub. + * + * @type {import("@fluid-tools/build-infrastructure").IFluidRepoLayout} + */ +module.exports = { + version: 1, + repoLayout: { + workspaces: { + "client": { + directory: ".", + releaseGroups: { + client: { + include: [...fluidScopes, "fluid-framework", "@types/jest-environment-puppeteer"], + rootPackageName: "client-release-group-root", + defaultInterdependencyRange: "workspace:~", + }, + examples: { + include: ["@fluid-example"], + defaultInterdependencyRange: "workspace:~", + }, + }, + }, + "build-tools": { + directory: "./build-tools", + releaseGroups: { + "build-tools": { + include: [...fluidScopes, "@fluid-example"], + rootPackageName: "build-tools-release-group-root", + defaultInterdependencyRange: "workspace:~", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=14", + }, + }, + }, + "server": { + directory: "./server/routerlicious", + releaseGroups: { + "server": { + include: [...fluidScopes, "@fluid-example", "tinylicious"], + rootPackageName: "server-release-group-root", + defaultInterdependencyRange: "workspace:~", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=30", + }, + }, + }, + "gitrest": { + directory: "server/gitrest", + releaseGroups: { + "gitrest": { + include: [...fluidScopes, "@fluid-example"], + rootPackageName: "gitrest-release-group-root", + defaultInterdependencyRange: "workspace:~", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=26", + }, + }, + }, + "historian": { + directory: "server/historian", + releaseGroups: { + "historian": { + include: [...fluidScopes, "@fluid-example"], + rootPackageName: "historian-release-group-root", + defaultInterdependencyRange: "workspace:~", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=25", + }, + }, + }, + + // legacy independent packages are all in their own workspaces, and are single-package release groups + "@fluid-tools/api-markdown-documenter": { + directory: "tools/api-markdown-documenter", + releaseGroups: { + "api-markdown-documenter": { + include: ["@fluid-tools/api-markdown-documenter"], + rootPackageName: "@fluid-tools/api-markdown-documenter", + defaultInterdependencyRange: "workspace:~", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=97", + }, + }, + }, + "@fluid-tools/benchmark": { + directory: "tools/benchmark", + releaseGroups: { + "benchmark": { + include: ["@fluid-tools/benchmark"], + rootPackageName: "@fluid-tools/benchmark", + defaultInterdependencyRange: "workspace:~", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=62", + }, + }, + }, + "@fluidframework/build-common": { + directory: "common/build/build-common", + releaseGroups: { + "build-common": { + include: ["@fluidframework/build-common"], + rootPackageName: "@fluidframework/build-common", + defaultInterdependencyRange: "workspace:~", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=3", + }, + }, + }, + "@fluidframework/common-utils": { + directory: "common/lib/common-utils", + releaseGroups: { + "common-utils": { + include: ["@fluidframework/common-utils"], + rootPackageName: "@fluidframework/common-utils", + defaultInterdependencyRange: "workspace:~", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=10", + }, + }, + }, + "@fluidframework/eslint-config-fluid": { + directory: "common/build/eslint-config-fluid", + releaseGroups: { + "eslint-config-fluid": { + include: ["@fluidframework/eslint-config-fluid"], + rootPackageName: "@fluidframework/eslint-config-fluid", + defaultInterdependencyRange: "workspace:~", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=7", + }, + }, + }, + "@fluid-internal/eslint-plugin-fluid": { + directory: "common/build/eslint-plugin-fluid", + releaseGroups: { + "eslint-plugin-fluid": { + include: ["@fluid-internal/eslint-plugin-fluid"], + rootPackageName: "@fluid-internal/eslint-plugin-fluid", + defaultInterdependencyRange: "workspace:~", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=135", + }, + }, + }, + "@fluid-internal/getkeys": { + directory: "tools/getkeys", + releaseGroups: { + "getkeys": { + include: ["@fluid-internal/getkeys"], + rootPackageName: "@fluid-internal/getkeys", + defaultInterdependencyRange: "workspace:~", + }, + }, + }, + "@fluidframework/protocol-definitions": { + directory: "common/lib/protocol-definitions", + releaseGroups: { + "protocol-definitions": { + include: ["@fluidframework/protocol-definitions"], + rootPackageName: "@fluidframework/protocol-definitions", + defaultInterdependencyRange: "workspace:~", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=67", + }, + }, + }, + "@fluidframework/test-tools": { + directory: "tools/test-tools", + releaseGroups: { + "test-tools": { + include: ["@fluidframework/test-tools"], + rootPackageName: "@fluidframework/test-tools", + defaultInterdependencyRange: "workspace:~", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=13", + }, + }, + }, + }, + }, +}; diff --git a/build-tools/package.json b/build-tools/package.json index b19589906125..2ddd4b74d3c2 100644 --- a/build-tools/package.json +++ b/build-tools/package.json @@ -1,5 +1,5 @@ { - "name": "root", + "name": "build-tools-release-group-root", "version": "0.50.0", "private": true, "homepage": "https://fluidframework.com", diff --git a/build-tools/packages/build-cli/src/test/commands/test-only-filter.test.ts b/build-tools/packages/build-cli/src/test/commands/test-only-filter.test.ts index f726977f63ab..c28c4afb0ff4 100644 --- a/build-tools/packages/build-cli/src/test/commands/test-only-filter.test.ts +++ b/build-tools/packages/build-cli/src/test/commands/test-only-filter.test.ts @@ -54,8 +54,8 @@ describe("flub test-only-filter", () => { // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment const output: jsonOutput = JSON.parse(ctx.stdout); const { selected, filtered } = output; - expect(selected).to.be.ofSize(4); - expect(filtered).to.be.ofSize(4); + expect(selected).to.be.ofSize(5); + expect(filtered).to.be.ofSize(5); }); test diff --git a/build-tools/packages/build-cli/src/test/filter.test.ts b/build-tools/packages/build-cli/src/test/filter.test.ts index 638239261577..7505a134c4fe 100644 --- a/build-tools/packages/build-cli/src/test/filter.test.ts +++ b/build-tools/packages/build-cli/src/test/filter.test.ts @@ -55,6 +55,7 @@ describe("filterPackages", () => { const names = actual.map((p) => p.name); expect(names).to.be.equalTo([ "@fluid-tools/build-cli", + "@fluid-tools/build-infrastructure", "@fluidframework/build-tools", "@fluidframework/bundle-size-tools", "@fluid-tools/version-tools", @@ -117,7 +118,11 @@ describe("filterPackages", () => { }; const actual = await filterPackages(packages, filters); const names = actual.map((p) => p.name); - expect(names).to.be.equalTo(["@fluid-tools/build-cli", "@fluid-tools/version-tools"]); + expect(names).to.be.equalTo([ + "@fluid-tools/build-cli", + "@fluid-tools/build-infrastructure", + "@fluid-tools/version-tools", + ]); }); it("scope and skipScope", async () => { @@ -151,6 +156,7 @@ describe("selectAndFilterPackages", () => { expect(names).to.be.containingAllOf([ "@fluid-tools/build-cli", + "@fluid-tools/build-infrastructure", "@fluidframework/build-tools", "@fluidframework/bundle-size-tools", "@fluid-tools/version-tools", @@ -206,6 +212,7 @@ describe("selectAndFilterPackages", () => { expect(names).to.be.equalTo([ "@fluid-tools/build-cli", + "@fluid-tools/build-infrastructure", "@fluidframework/build-tools", "@fluidframework/bundle-size-tools", "@fluid-tools/version-tools", @@ -330,7 +337,11 @@ describe("selectAndFilterPackages", () => { const { filtered } = await selectAndFilterPackages(context, selectionOptions, filters); const names = filtered.map((p) => p.name); - expect(names).to.be.equalTo(["@fluid-tools/build-cli", "@fluid-tools/version-tools"]); + expect(names).to.be.equalTo([ + "@fluid-tools/build-cli", + "@fluid-tools/build-infrastructure", + "@fluid-tools/version-tools", + ]); }); it("select release group, filter skipScopes", async () => { diff --git a/build-tools/packages/build-infrastructure/.eslintrc.cjs b/build-tools/packages/build-infrastructure/.eslintrc.cjs new file mode 100644 index 000000000000..2708d36e5a04 --- /dev/null +++ b/build-tools/packages/build-infrastructure/.eslintrc.cjs @@ -0,0 +1,38 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +module.exports = { + plugins: ["@typescript-eslint", "chai-friendly"], + extends: [ + // eslint-disable-next-line node/no-extraneous-require + require.resolve("@fluidframework/eslint-config-fluid/recommended"), + "prettier", + ], + parserOptions: { + project: ["./tsconfig.json", "./src/test/tsconfig.json"], + }, + rules: { + // This package is exclusively used in a Node.js context + "import/no-nodejs-modules": "off", + + "tsdoc/syntax": ["warn"], + }, + overrides: [ + { + // Rules only for test files + files: ["*.spec.ts", "src/test/**"], + rules: { + // Test files can import from anywhere + "import/no-internal-modules": "off", + + // Superseded by chai-friendly/no-unused-expressions + "no-unused-expressions": "off", + "@typescript-eslint/no-unused-expressions": "off", + + "chai-friendly/no-unused-expressions": "error", + }, + }, + ], +}; diff --git a/build-tools/packages/build-infrastructure/.gitignore b/build-tools/packages/build-infrastructure/.gitignore new file mode 100644 index 000000000000..2ea48a41c7ba --- /dev/null +++ b/build-tools/packages/build-infrastructure/.gitignore @@ -0,0 +1,11 @@ +*-debug.log +*-error.log +/.nyc_output +/coverage +/dist +/lib +!/src/lib +!/test/lib +/tmp +node_modules +oclif.manifest.json diff --git a/build-tools/packages/build-infrastructure/.mocharc.json b/build-tools/packages/build-infrastructure/.mocharc.json new file mode 100644 index 000000000000..b8386c9dc3e8 --- /dev/null +++ b/build-tools/packages/build-infrastructure/.mocharc.json @@ -0,0 +1,7 @@ +{ + "require": ["ts-node/register"], + "watch-extensions": ["ts", "cts", "mts"], + "recursive": true, + "reporter": "mocha-multi-reporters", + "reporter-options": "configFile=mocha-multi-reporter-config.json" +} diff --git a/build-tools/packages/build-infrastructure/.npmignore b/build-tools/packages/build-infrastructure/.npmignore new file mode 100644 index 000000000000..e1430c52bec5 --- /dev/null +++ b/build-tools/packages/build-infrastructure/.npmignore @@ -0,0 +1,14 @@ +.eslintignore +.eslintrc.cjs +.mocharc.json +.prettierignore +*.log +**/_api-extractor-temp/** +**/*.tsbuildinfo +dist/test +docs +lib/test +nyc +packlist.txt +src +test \ No newline at end of file diff --git a/build-tools/packages/build-infrastructure/.prettierignore b/build-tools/packages/build-infrastructure/.prettierignore new file mode 100644 index 000000000000..ec7e1e8da581 --- /dev/null +++ b/build-tools/packages/build-infrastructure/.prettierignore @@ -0,0 +1,3 @@ +# Ignore all files. This package only uses biome for formatting. +**/*.* +*/* diff --git a/build-tools/packages/build-infrastructure/LICENSE b/build-tools/packages/build-infrastructure/LICENSE new file mode 100644 index 000000000000..60af0a6a40e9 --- /dev/null +++ b/build-tools/packages/build-infrastructure/LICENSE @@ -0,0 +1,21 @@ +Copyright (c) Microsoft Corporation and contributors. All rights reserved. + +MIT License + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/build-tools/packages/build-infrastructure/README.md b/build-tools/packages/build-infrastructure/README.md new file mode 100644 index 000000000000..f98e1d20a2a1 --- /dev/null +++ b/build-tools/packages/build-infrastructure/README.md @@ -0,0 +1,239 @@ +# @fluid-tools/build-infrastructure + +This package contains types and helper functions that are used across multiple build-tools packages, including +`@fluidframework/build-tools` and `@fluid-tools/build-cli`. + +The primary purpose of this package is to provide a common way to organize npm packages into groups called release +groups, and leverages workspaces functionality provided by package managers like npm, yarn, and pnpm to manage +interdependencies between packages across a Fluid repo. It then provides APIs to select, filter, and work with those +package groups. + +## API Overview + +The API is built around four key types which form a hierarchy: `IFluidRepo`, `IWorkspace`, `IReleaseGroup`, and +`IPackage`. For the purposes of this documentation, the terms "Fluid repo," "workspace," "release group," and "package" +generally refer to these types. + +Conceptually, a **Fluid repo** is a way to organize npm packages into groups for versioning, release, and dependency +management. A Fluid repo can contain multiple **workspaces**, each of which may contain one or more **release groups**. + +### The Fluid repo + +The primary entrypoint for the API is the `IFluidRepo` type. A Fluid repo can contain multiple workspaces and release +groups. Both workspaces and release groups represent ways to organize packages in the repo, but their purpose and +function are different. + +### Workspaces + +Workspaces are generally a feature provided by the package manager (npm, yarn, pnpm, etc.). A workspace defines the +_physical layout_ of the packages within it. A workspace is rooted in a particular folder, and uses the configuration +within that folder to determine what packages it contains. The config used is specific to the package manager. + +The workspace is also the boundary at which dependencies are installed and managed. When you install dependencies for a +package in a workspace, all dependencies for all packages in the workspace will be installed. Within a workspace, it is +trivial to link multiple packages so they can depend on one another. The `IWorkspace` type is a thin wrapper on top of +these package manager features. + +Importantly, this package does not attempt to re-implement any features provided by workspaces themselves. Users are +expected to configure their package managers' workspace features in addition to the Fluid repo configuration. + +A Fluid repo will only load packages identified by the package manager's workspace feature. That is, any package in the +repo that is not configured as part of a workspace is invisible to tools using the Fluid repo. + +### Release groups + +While workspaces manage dependencies and physical layout of packages, release groups are focused on groups of packages +that are _versioned and released together_. Release groups are always a subset of a workspace, and must contain at least +one package. **Release groups cannot span multiple workspaces.** + + +> [!IMPORTANT] +> A workspace _must_ have at least one release group, and all packages must be a part of a release group. + +> [!NOTE] +> In the v0 version of build-tools, release groups and workspaces have a 1:1 relationship. In contrast, with the types +> defined here in build-infrastructure, workspaces can contain multiple release groups. + +### Packages + +Packages are the lowest-level entity in build-infrastructure. A package _must_ be a part of both a release group and +workspace in order to be managed with build-infrastructure. In general, developers should prefer using release groups - +which are ultimately just groups of packages - to working with individual packages. + +### What about "independent packages?" + +In the v0 version of build-tools, we have the concept of _independent packages_: packages that are not part of a release +group and are released independently. **This concept no longer exists. There are only release groups.** Packages that +release independently can either be part of a single-package workspace (and release group), or they can be part of +another larger workspace, contained within a single-package release group. + +## Features + +### Git repo capabilities + +A Fluid repo is often contained within a Git repository, and some functionality expects to be used within a Git +repository. Features that need to execute Git operations can asynchronously retrieve the SimpleGit instance using the +`IFluidRepo.getGitRepository` API. If the Fluid repo is not within a Git repo, then that call will throw a +`NotInGitRepository` exception that callers should handle appropriately. If they don't, though, the exception makes it +clear what has happened. + +> [!NOTE] +> +> This design addresses a major problem with build-tools v0, which was that code often made assumptions that it was +> operating within a Git repo. That's often true, and some fetures can and should only work in that context, but the +> implementation attempted to load the Git functionality blindly and would fail outright outside a Git context. With +> `IFluidRepo`, the Git integration is more loosely coupled and the APIs make it clearer that it is not safe to assume +> the presence of a Git repo. + +### Package selection and filtering APIs + +The `IFluidRepo` object provides access to workspaces, release groups, and their constituent packages, but often one wants +to operate on a subset of all packages in the repo. To support this, build-infrastructure provides a selection and +filtering API. Packages can be selected based on criteria like workspace and release group, and the lists can be further +filtered by scope or private/not private. Advanced filtering not covered by the built-in filters can be implemented +using `Array.prototype.filter` on the results of package selection. + +### Built-in command-line tool to examine repo layout and config + +The included CLI tool makes it easy to examine the contents and layout of a Fluid repo. See [the CLI +documentation](./docs/cli.md) for more information. + +### Loading old config formats + +The `repoPackages` configuration currently used by fluid-build will be loaded if the newer `repoLayout` config can't be +found. This is for back-compat only and will not be maintained indefinitely. Users should convert to `repoLayout` when +possible. + +## Configuration + +Configuration for the repo layout is stored in a config file at the root of the repo. This can either be part of the +`fluidBuild.config.cjs` file in the `repoLayout` property, or in an independent config file named +`repoLayout.config.cjs` (or mjs). + +### Example + +The following example configures three workspaces demonstrating the three archetypes - a workspace with multiple release +groups, a workspace with a single release group that contains multiple packages, and a workspace with a single release +group that contains a single package. + +```js +repoLayout: { + workspaces: { + // This is the name of the workspace which is how it's referenced in the API. All workspaces in a Fluid repo must + // have a unique name. + "client": { + // This workspace is rooted at the root of the Git repo. + directory: ".", + releaseGroups: { + // This key is the name of the release group. All release groups in a Fluid repo must have a unique name. + client: { + // The include property can contain package names OR package scopes. If + // a scope is provided, all packages with that scope will be a part of + // the release group. + include: [ + // Include all the Fluid Framework scopes and packages except for + // @fluid-example. + "@fluidframework", + "@fluid-experimental", + "@fluid-internal", + "@fluid-private", + "@fluid-tools", + // This private package is part of the client release group + "@types/jest-environment-puppeteer" + "fluid-framework", + ], + // A release group can have an OPTIONAL root package. This package + // is typically private and is similar to the root package for a workspace. + // This release group root package may be useful to store scripts or other + // configuration that only applies on the release group, + rootPackageName: "client-release-group-root", + + // A release group may have an ADO pipeline URL associated with it. This + // URL is used to provide direct links to the pipeline when running releases. + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=12", + }, + examples: { + // This release group contains only the @fluid-example packages. + include: ["@fluid-example"], + // Release group root packages are optional but can be useful to store scripts that are tuned to + // apply to only that release group. + rootPackageName: "examples-release-group-root", + }, + // If any packages in the workspace don't match a release group, loading the + // repo layout config will throw an error. + }, + }, + "build-tools": { + // This workspace is rooted in the build-tools folder. This folder must contain + // a workspace config. The specific config depends on the package manager being used. + directory: "./build-tools", + releaseGroups: { + // Release groups can have the same name as workspaces, but all release group names + // must be unique regardless of the workspace they belong to. + "build-tools": { + include: [ + // Include all Fluid Framework scopes. Only packages contained in the workspace + // will be included, so it is safe to use the same scopes in multiple release + // group definitions as long as they're in different workspaces. + "@fluidframework", + "@fluid-example", + "@fluid-experimental", + "@fluid-internal", + "@fluid-private", + "@fluid-tools", + ], + rootPackageName: "build-tools-release-group-root", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=14", + }, + }, + }, + }, +} +``` + +### Loading a Fluid repo from a configuration file + +To load a Fluid repo, you use the `loadFluidRepo` function. You can pass in a path to a Git repository root, or if one +is not provided, then the Git repository nearest to the working directory can be used. + +This function will look for a repo layout configuration in that folder and load the workspaces, release groups, and +packages accordingly and return an `IFluidRepo` object that includes Maps of workspaces, release groups, and packages as +properties. + +## Other APIs + +### Type guards + +You can use the `isIPackage` and `isIReleaseGroup` functions to determine if an object is an `IPackage` or +`IReleaseGroup` respectively. + +### Base classes + +The `PackageBase` abstract class can be used as a base class to create custom `IPackage` classes. + +## Miscellaneous improvements + +### Fluid repos can be rooted anywhere + +Fluid repos are rooted where their config file is located, _not_ at the root of a Git repo. There can be multiple Fluid +repos within a Git repo, though this is usually only needed for testing. In typical use only a single Fluid repo per +Git repo is needed. However, the Fluid repo does _not_ need to be rooted at the root of Git repo, and code should not +assume that the root of the Fluid repo is the same as the root of a Git repo. + +### Better testing + +There is now a test project within the repo that is a fully functional Fluid repo. There are basic unit tests that verify the +loading of the Fluid repo config and that packages are organized as expected. This is a dramatic improvement from v0 +build-tools, in which all package traversal logic was effectively untested. + +There are also tests for the selection and filtering APIs. + +This infrastructure also provides a foundation for further test improvements, and testing other new features of Fluid +repos. In the past it was challenging to add new features because there was no way to test those features effectively. +That should be much easier now. + +## Known gaps + +- Inadequate testing of git-related APIs - can we mock git somehow? diff --git a/build-tools/packages/build-infrastructure/api-extractor.json b/build-tools/packages/build-infrastructure/api-extractor.json new file mode 100644 index 000000000000..c206d410609d --- /dev/null +++ b/build-tools/packages/build-infrastructure/api-extractor.json @@ -0,0 +1,5 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", + "extends": "../../api-extractor-base.json", + "mainEntryPointFilePath": "/lib/index.d.ts" +} diff --git a/build-tools/packages/build-infrastructure/api-markdown.mjs b/build-tools/packages/build-infrastructure/api-markdown.mjs new file mode 100644 index 000000000000..5b7601e12826 --- /dev/null +++ b/build-tools/packages/build-infrastructure/api-markdown.mjs @@ -0,0 +1,25 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +import path from "node:path"; +import { fileURLToPath } from "node:url"; + +import { MarkdownRenderer, loadModel } from "@fluid-tools/api-markdown-documenter"; + +const dirname = path.dirname(fileURLToPath(import.meta.url)); +const inputDir = path.resolve(dirname, "_api-extractor-temp", "doc-models"); +const outputDir = path.resolve(dirname, "docs"); + +console.debug(dirname, inputDir, outputDir); + +// Create the API Model from our API reports +const apiModel = await loadModel(inputDir); + +const config = { + apiModel, + uriRoot: ".", +}; + +await MarkdownRenderer.renderApiModel(config, outputDir); diff --git a/build-tools/packages/build-infrastructure/api-report/build-infrastructure.api.md b/build-tools/packages/build-infrastructure/api-report/build-infrastructure.api.md new file mode 100644 index 000000000000..553e59a1b99f --- /dev/null +++ b/build-tools/packages/build-infrastructure/api-report/build-infrastructure.api.md @@ -0,0 +1,196 @@ +## API Report File for "@fluid-tools/build-infrastructure" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +import type { Opaque } from 'type-fest'; +import type { PackageJson as PackageJson_2 } from 'type-fest'; +import type { SetRequired } from 'type-fest'; +import { SimpleGit } from 'simple-git'; + +// @public (undocumented) +export type AdditionalPackageProps = Record | undefined; + +// @public +export interface FluidPackageJsonFields { + pnpm?: { + overrides?: Record; + }; +} + +// @public +export const FLUIDREPO_CONFIG_VERSION = 1; + +// @public +export function getFluidRepoLayout(searchPath: string, noCache?: boolean): { + config: IFluidRepoLayout; + configFilePath: string; +}; + +// @public @deprecated +export interface IFluidBuildDir { + directory: string; +} + +// @public @deprecated (undocumented) +export type IFluidBuildDirEntry = string | IFluidBuildDir | (string | IFluidBuildDir)[]; + +// @public @deprecated (undocumented) +export interface IFluidBuildDirs { + // (undocumented) + [name: string]: IFluidBuildDirEntry; +} + +// @public +export interface IFluidRepo

extends Reloadable { + configuration: IFluidRepoLayout; + getGitRepository(): Promise>; + getPackageReleaseGroup(pkg: Readonly

): Readonly; + getPackageWorkspace(pkg: Readonly

): Readonly; + packages: Map; + relativeToRepo(p: string): string; + releaseGroups: Map; + root: string; + upstreamRemotePartialUrl?: string; + workspaces: Map; +} + +// @public +export interface IFluidRepoLayout { + repoLayout?: { + workspaces: { + [name: string]: WorkspaceDefinition; + }; + }; + // @deprecated + repoPackages?: IFluidBuildDirs; + version: typeof FLUIDREPO_CONFIG_VERSION; +} + +// @public +export interface Installable { + checkInstall(): Promise; + install(updateLockfile: boolean): Promise; +} + +// @public +export interface IPackage extends Installable, Reloadable { + combinedDependencies: Generator; + readonly directory: string; + getScript(name: string): string | undefined; + isReleaseGroupRoot: boolean; + readonly isWorkspaceRoot: boolean; + readonly name: PackageName; + readonly nameColored: string; + packageJson: J; + readonly packageJsonFilePath: string; + readonly packageManager: IPackageManager; + readonly private: boolean; + releaseGroup: ReleaseGroupName; + savePackageJson(): Promise; + // (undocumented) + toString(): string; + readonly version: string; + readonly workspace: IWorkspace; +} + +// @public +export interface IPackageManager { + // (undocumented) + installCommand(updateLockfile: boolean): string; + // (undocumented) + readonly lockfileName: string; + // (undocumented) + readonly name: PackageManagerName; +} + +// @public +export interface IReleaseGroup extends Reloadable { + readonly adoPipelineUrl?: string; + readonly name: ReleaseGroupName; + readonly packages: IPackage[]; + readonly releaseGroupDependencies: IReleaseGroup[]; + readonly rootPackage?: IPackage; + // (undocumented) + toString(): string; + readonly version: string; + readonly workspace: IWorkspace; +} + +// @public +export function isIPackage(pkg: any): pkg is IPackage; + +// @public +export function isIReleaseGroup(toCheck: Exclude): toCheck is IReleaseGroup; + +// @public +export interface IWorkspace extends Installable, Reloadable { + directory: string; + name: WorkspaceName; + packages: IPackage[]; + releaseGroups: Map; + rootPackage: IPackage; + // (undocumented) + toString(): string; +} + +// @public +export class NotInGitRepository extends Error { + constructor(path: string); + // (undocumented) + readonly path: string; +} + +// @public +export interface PackageDependency { + // (undocumented) + depClass: "prod" | "dev" | "peer"; + // (undocumented) + name: PackageName; + // (undocumented) + version: string; +} + +// @public (undocumented) +export type PackageJson = SetRequired; + +// @public +export type PackageManagerName = "npm" | "pnpm" | "yarn"; + +// @public +export type PackageName = Opaque; + +// @public (undocumented) +export interface ReleaseGroupDefinition { + adoPipelineUrl?: string; + exclude?: string[]; + include: string[]; + rootPackageName?: string; +} + +// @public +export type ReleaseGroupName = Opaque; + +// @public +export interface Reloadable { + // (undocumented) + reload(): void; +} + +// @public (undocumented) +export interface WorkspaceDefinition { + // (undocumented) + directory: string; + // (undocumented) + releaseGroups: { + [name: string]: ReleaseGroupDefinition; + }; +} + +// @public +export type WorkspaceName = Opaque; + +// (No @packageDocumentation comment for this package) + +``` diff --git a/build-tools/packages/build-infrastructure/bin/dev.cmd b/build-tools/packages/build-infrastructure/bin/dev.cmd new file mode 100644 index 000000000000..077b57ae7528 --- /dev/null +++ b/build-tools/packages/build-infrastructure/bin/dev.cmd @@ -0,0 +1,3 @@ +@echo off + +node "%~dp0\dev" %* \ No newline at end of file diff --git a/build-tools/packages/build-infrastructure/bin/dev.mjs b/build-tools/packages/build-infrastructure/bin/dev.mjs new file mode 100755 index 000000000000..e99fc8600c93 --- /dev/null +++ b/build-tools/packages/build-infrastructure/bin/dev.mjs @@ -0,0 +1,9 @@ +#!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +import { execute } from "@oclif/core"; + +await execute({ development: true, dir: import.meta.url }); diff --git a/build-tools/packages/build-infrastructure/bin/run.cmd b/build-tools/packages/build-infrastructure/bin/run.cmd new file mode 100644 index 000000000000..968fc30758e6 --- /dev/null +++ b/build-tools/packages/build-infrastructure/bin/run.cmd @@ -0,0 +1,3 @@ +@echo off + +node "%~dp0\run" %* diff --git a/build-tools/packages/build-infrastructure/bin/run.mjs b/build-tools/packages/build-infrastructure/bin/run.mjs new file mode 100755 index 000000000000..040698684305 --- /dev/null +++ b/build-tools/packages/build-infrastructure/bin/run.mjs @@ -0,0 +1,9 @@ +#!/usr/bin/env node +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +import { execute } from "@oclif/core"; + +await execute({ dir: import.meta.url }); diff --git a/build-tools/packages/build-infrastructure/biome.jsonc b/build-tools/packages/build-infrastructure/biome.jsonc new file mode 100644 index 000000000000..504f9419b45f --- /dev/null +++ b/build-tools/packages/build-infrastructure/biome.jsonc @@ -0,0 +1,7 @@ +{ + "$schema": "./node_modules/@biomejs/biome/configuration_schema.json", + "extends": ["../../../biome.jsonc"], + "files": { + "ignore": ["src/test/data/biome/empty.jsonc"] + } +} diff --git a/build-tools/packages/build-infrastructure/docs/README.md b/build-tools/packages/build-infrastructure/docs/README.md new file mode 100644 index 000000000000..215ab6afe08e --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/README.md @@ -0,0 +1,293 @@ +**@fluid-tools/build-infrastructure** • **Docs** + +*** + +# @fluid-tools/build-infrastructure + +This package contains types and helper functions that are used across multiple build-tools packages, including +`@fluidframework/build-tools` and `@fluid-tools/build-cli`. + +The primary purpose of this package is to provide a common way to organize npm packages into groups called release +groups, and leverages workspaces functionality provided by package managers like npm, yarn, and pnpm to manage +interdependencies between packages across a Fluid repo. It then provides APIs to select, filter, and work with those +package groups. + +## API Overview + +The API is built around four key types which form a hierarchy: `IFluidRepo`, `IWorkspace`, `IReleaseGroup`, and +`IPackage`. For the purposes of this documentation, the terms "Fluid repo," "workspace," "release group," and "package" +generally refer to these types. + +Conceptually, a **Fluid repo** is a way to organize npm packages into groups for versioning, release, and dependency +management. A Fluid repo can contain multiple **workspaces**, each of which may contain one or more **release groups**. + +### The Fluid repo + +The primary entrypoint for the API is the `IFluidRepo` type. A Fluid repo can contain multiple workspaces and release +groups. Both workspaces and release groups represent ways to organize packages in the repo, but their purpose and +function are different. + +### Workspaces + +Workspaces are generally a feature provided by the package manager (npm, yarn, pnpm, etc.). A workspace defines the +_physical layout_ of the packages within it. A workspace is rooted in a particular folder, and uses the configuration +within that folder to determine what packages it contains. The config used is specific to the package manager. + +The workspace is also the boundary at which dependencies are installed and managed. When you install dependencies for a +package in a workspace, all dependencies for all packages in the workspace will be installed. Within a workspace, it is +trivial to link multiple packages so they can depend on one another. The `IWorkspace` type is a thin wrapper on top of +these package manager features. + +Importantly, this package does not attempt to re-implement any features provided by workspaces themselves. Users are +expected to configure their package managers' workspace features in addition to the Fluid repo configuration. + +A Fluid repo will only load packages identified by the package manager's workspace feature. That is, any package in the +repo that is not configured as part of a workspace is invisible to tools using the Fluid repo. + +### Release groups + +While workspaces manage dependencies and physical layout of packages, release groups are focused on groups of packages +that are _versioned and released together_. Release groups are always a subset of a workspace, and must contain at least +one package. **Release groups cannot span multiple workspaces.** + +> [!IMPORTANT] +> A workspace _must_ have at least one release group, and all packages must be a part of a release group. + +> [!NOTE] +> In the v0 version of build-tools, release groups and workspaces have a 1:1 relationship. In contrast, with the types +> defined here in build-infrastructure, workspaces can contain multiple release groups. + +### Packages + +Packages are the lowest-level entity in build-infrastructure. A package _must_ be a part of both a release group and +workspace in order to be managed with build-infrastructure. In general, developers should prefer using release groups - +which are ultimately just groups of packages - to working with individual packages. + +### What about "independent packages?" + +In the v0 version of build-tools, we have the concept of _independent packages_: packages that are not part of a release +group and are released independently. **This concept no longer exists. There are only release groups.** Packages that +release independently can either be part of a single-package workspace (and release group), or they can be part of +another larger workspace, contained within a single-package release group. + +## Features + +### Git repo capabilities + +A Fluid repo is often contained within a Git repository, and some functionality expects to be used within a Git +repository. Features that need to execute Git operations can asynchronously retrieve the SimpleGit instance using the +`IFluidRepo.getGitRepository` API. If the Fluid repo is not within a Git repo, then that call will throw a +`NotInGitRepository` exception that callers should handle appropriately. If they don't, though, the exception makes it +clear what has happened. + +> [!NOTE] +> +> This design addresses a major problem with build-tools v0, which was that code often made assumptions that it was +> operating within a Git repo. That's often true, and some fetures can and should only work in that context, but the +> implementation attempted to load the Git functionality blindly and would fail outright outside a Git context. With +> `IFluidRepo`, the Git integration is more loosely coupled and the APIs make it clearer that it is not safe to assume +> the presence of a Git repo. + +### Package selection and filtering APIs + +The `IFluidRepo` object provides access to workspaces, release groups, and their constituent packages, but often one wants +to operate on a subset of all packages in the repo. To support this, build-infrastructure provides a selection and +filtering API. Packages can be selected based on criteria like workspace and release group, and the lists can be further +filtered by scope or private/not private. Advanced filtering not covered by the built-in filters can be implemented +using `Array.prototype.filter` on the results of package selection. + +### Built-in command-line tool to examine repo layout and config + +The included CLI tool makes it easy to examine the contents and layout of a Fluid repo. See [the CLI +documentation](./docs/cli.md) for more information. + +### Loading old config formats + +The `repoPackages` configuration currently used by fluid-build will be loaded if the newer `repoLayout` config can't be +found. This is for back-compat only and will not be maintained indefinitely. Users should convert to `repoLayout` when +possible. + +## Configuration + +Configuration for the repo layout is stored in a config file at the root of the repo. This can either be part of the +`fluidBuild.config.cjs` file in the `repoLayout` property, or in an independent config file named +`repoLayout.config.cjs` (or mjs). + +### Example + +The following example configures three workspaces demonstrating the three archetypes - a workspace with multiple release +groups, a workspace with a single release group that contains multiple packages, and a workspace with a single release +group that contains a single package. + +```js +repoLayout: { + workspaces: { + // This is the name of the workspace which is how it's referenced in the API. All workspaces in a Fluid repo must + // have a unique name. + "client": { + // This workspace is rooted at the root of the Git repo. + directory: ".", + releaseGroups: { + // This key is the name of the release group. All release groups in a Fluid repo must have a unique name. + client: { + // The include property can contain package names OR package scopes. If + // a scope is provided, all packages with that scope will be a part of + // the release group. + include: [ + // Include all the Fluid Framework scopes and packages except for + // @fluid-example. + "@fluidframework", + "@fluid-experimental", + "@fluid-internal", + "@fluid-private", + "@fluid-tools", + // This private package is part of the client release group + "@types/jest-environment-puppeteer" + "fluid-framework", + ], + // A release group can have an OPTIONAL root package. This package + // is typically private and is similar to the root package for a workspace. + // This release group root package may be useful to store scripts or other + // configuration that only applies on the release group, + rootPackageName: "client-release-group-root", + + // A release group may have an ADO pipeline URL associated with it. This + // URL is used to provide direct links to the pipeline when running releases. + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=12", + }, + examples: { + // This release group contains only the @fluid-example packages. + include: ["@fluid-example"], + // Release group root packages are optional but can be useful to store scripts that are tuned to + // apply to only that release group. + rootPackageName: "examples-release-group-root", + }, + // If any packages in the workspace don't match a release group, loading the + // repo layout config will throw an error. + }, + }, + "build-tools": { + // This workspace is rooted in the build-tools folder. This folder must contain + // a workspace config. The specific config depends on the package manager being used. + directory: "./build-tools", + releaseGroups: { + // Release groups can have the same name as workspaces, but all release group names + // must be unique regardless of the workspace they belong to. + "build-tools": { + include: [ + // Include all Fluid Framework scopes. Only packages contained in the workspace + // will be included, so it is safe to use the same scopes in multiple release + // group definitions as long as they're in different workspaces. + "@fluidframework", + "@fluid-example", + "@fluid-experimental", + "@fluid-internal", + "@fluid-private", + "@fluid-tools", + ], + rootPackageName: "build-tools-release-group-root", + adoPipelineUrl: + "https://dev.azure.com/fluidframework/internal/_build?definitionId=14", + }, + }, + }, + }, +} +``` + +### Loading a Fluid repo from a configuration file + +To load a Fluid repo, you use the `loadFluidRepo` function. You can pass in a path to a Git repository root, or if one +is not provided, then the Git repository nearest to the working directory can be used. + +This function will look for a repo layout configuration in that folder and load the workspaces, release groups, and +packages accordingly and return an `IFluidRepo` object that includes Maps of workspaces, release groups, and packages as +properties. + +## Other APIs + +### Type guards + +You can use the `isIPackage` and `isIReleaseGroup` functions to determine if an object is an `IPackage` or +`IReleaseGroup` respectively. + +### Base classes + +The `PackageBase` abstract class can be used as a base class to create custom `IPackage` classes. + +## Miscellaneous improvements + +### Fluid repos can be rooted anywhere + +Fluid repos are rooted where their config file is located, _not_ at the root of a Git repo. There can be multiple Fluid +repos within a Git repo, though this is usually only needed for testing. In typical use only a single Fluid repo per +Git repo is needed. However, the Fluid repo does _not_ need to be rooted at the root of Git repo, and code should not +assume that the root of the Fluid repo is the same as the root of a Git repo. + +### Better testing + +There is now a test project within the repo that is a fully functional Fluid repo. There are basic unit tests that verify the +loading of the Fluid repo config and that packages are organized as expected. This is a dramatic improvement from v0 +build-tools, in which all package traversal logic was effectively untested. + +There are also tests for the selection and filtering APIs. + +This infrastructure also provides a foundation for further test improvements, and testing other new features of Fluid +repos. In the past it was challenging to add new features because there was no way to test those features effectively. +That should be much easier now. + +## Known gaps + +- Inadequate testing of git-related APIs - can we mock git somehow? + +build-infrastructure package comment. + +## Group + +API + +## Category + +API + +## Classes + +- [NotInGitRepository](classes/NotInGitRepository.md) + +## Interfaces + +- [FluidPackageJsonFields](interfaces/FluidPackageJsonFields.md) +- [IFluidBuildDir](interfaces/IFluidBuildDir.md) +- [IFluidBuildDirs](interfaces/IFluidBuildDirs.md) +- [IFluidRepo](interfaces/IFluidRepo.md) +- [IFluidRepoLayout](interfaces/IFluidRepoLayout.md) +- [Installable](interfaces/Installable.md) +- [IPackage](interfaces/IPackage.md) +- [IPackageManager](interfaces/IPackageManager.md) +- [IReleaseGroup](interfaces/IReleaseGroup.md) +- [IWorkspace](interfaces/IWorkspace.md) +- [PackageDependency](interfaces/PackageDependency.md) +- [ReleaseGroupDefinition](interfaces/ReleaseGroupDefinition.md) +- [Reloadable](interfaces/Reloadable.md) +- [WorkspaceDefinition](interfaces/WorkspaceDefinition.md) + +## Type Aliases + +- [AdditionalPackageProps](type-aliases/AdditionalPackageProps.md) +- [IFluidBuildDirEntry](type-aliases/IFluidBuildDirEntry.md) +- [PackageJson](type-aliases/PackageJson.md) +- [PackageManagerName](type-aliases/PackageManagerName.md) +- [PackageName](type-aliases/PackageName.md) +- [ReleaseGroupName](type-aliases/ReleaseGroupName.md) +- [WorkspaceName](type-aliases/WorkspaceName.md) + +## Variables + +- [FLUIDREPO\_CONFIG\_VERSION](variables/FLUIDREPO_CONFIG_VERSION.md) + +## Functions + +- [getFluidRepoLayout](functions/getFluidRepoLayout.md) +- [isIPackage](functions/isIPackage.md) +- [isIReleaseGroup](functions/isIReleaseGroup.md) diff --git a/build-tools/packages/build-infrastructure/docs/classes/NotInGitRepository.md b/build-tools/packages/build-infrastructure/docs/classes/NotInGitRepository.md new file mode 100644 index 000000000000..4b6ef8183edb --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/classes/NotInGitRepository.md @@ -0,0 +1,173 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / NotInGitRepository + +# Class: NotInGitRepository + +An error thrown when a path is not within a Git repository. + +## Extends + +- `Error` + +## Constructors + +### new NotInGitRepository() + +```ts +new NotInGitRepository(path): NotInGitRepository +``` + +#### Parameters + +• **path**: `string` + +#### Returns + +[`NotInGitRepository`](NotInGitRepository.md) + +#### Overrides + +`Error.constructor` + +#### Defined in + +[packages/build-infrastructure/src/errors.ts:10](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/errors.ts#L10) + +## Properties + +### message + +```ts +message: string; +``` + +#### Inherited from + +`Error.message` + +#### Defined in + +node\_modules/.pnpm/typescript@5.4.5/node\_modules/typescript/lib/lib.es5.d.ts:1077 + +*** + +### name + +```ts +name: string; +``` + +#### Inherited from + +`Error.name` + +#### Defined in + +node\_modules/.pnpm/typescript@5.4.5/node\_modules/typescript/lib/lib.es5.d.ts:1076 + +*** + +### path + +```ts +readonly path: string; +``` + +#### Defined in + +[packages/build-infrastructure/src/errors.ts:10](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/errors.ts#L10) + +*** + +### stack? + +```ts +optional stack: string; +``` + +#### Inherited from + +`Error.stack` + +#### Defined in + +node\_modules/.pnpm/typescript@5.4.5/node\_modules/typescript/lib/lib.es5.d.ts:1078 + +*** + +### prepareStackTrace()? + +```ts +static optional prepareStackTrace: (err, stackTraces) => any; +``` + +Optional override for formatting stack traces + +#### Parameters + +• **err**: `Error` + +• **stackTraces**: `CallSite`[] + +#### Returns + +`any` + +#### See + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +`Error.prepareStackTrace` + +#### Defined in + +node\_modules/.pnpm/@types+node@18.18.7/node\_modules/@types/node/globals.d.ts:11 + +*** + +### stackTraceLimit + +```ts +static stackTraceLimit: number; +``` + +#### Inherited from + +`Error.stackTraceLimit` + +#### Defined in + +node\_modules/.pnpm/@types+node@18.18.7/node\_modules/@types/node/globals.d.ts:13 + +## Methods + +### captureStackTrace() + +```ts +static captureStackTrace(targetObject, constructorOpt?): void +``` + +Create .stack property on a target object + +#### Parameters + +• **targetObject**: `object` + +• **constructorOpt?**: `Function` + +#### Returns + +`void` + +#### Inherited from + +`Error.captureStackTrace` + +#### Defined in + +node\_modules/.pnpm/@types+node@18.18.7/node\_modules/@types/node/globals.d.ts:4 diff --git a/build-tools/packages/build-infrastructure/docs/functions/getFluidRepoLayout.md b/build-tools/packages/build-infrastructure/docs/functions/getFluidRepoLayout.md new file mode 100644 index 000000000000..5a51a6bd3dd5 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/functions/getFluidRepoLayout.md @@ -0,0 +1,49 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / getFluidRepoLayout + +# Function: getFluidRepoLayout() + +```ts +function getFluidRepoLayout(searchPath, noCache): object +``` + +Search a path for a repo layout config file, and return the parsed config and the path to the config file. + +## Parameters + +• **searchPath**: `string` + +The path to start searching for config files in. + +• **noCache**: `boolean` = `false` + +If true, the config cache will be cleared and the config will be reloaded. + +## Returns + +`object` + +The loaded repoLayout config and the path to the config file. + +### config + +```ts +config: IFluidRepoLayout; +``` + +### configFilePath + +```ts +configFilePath: string; +``` + +## Throws + +If a config is not found or if the config version is not supported. + +## Defined in + +[packages/build-infrastructure/src/config.ts:198](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L198) diff --git a/build-tools/packages/build-infrastructure/docs/functions/isIPackage.md b/build-tools/packages/build-infrastructure/docs/functions/isIPackage.md new file mode 100644 index 000000000000..e2219b075de6 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/functions/isIPackage.md @@ -0,0 +1,25 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / isIPackage + +# Function: isIPackage() + +```ts +function isIPackage(pkg): pkg is IPackage +``` + +A type guard that returns `true` if the item is an [IPackage](../interfaces/IPackage.md). + +## Parameters + +• **pkg**: `any` + +## Returns + +`pkg is IPackage` + +## Defined in + +[packages/build-infrastructure/src/types.ts:379](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L379) diff --git a/build-tools/packages/build-infrastructure/docs/functions/isIReleaseGroup.md b/build-tools/packages/build-infrastructure/docs/functions/isIReleaseGroup.md new file mode 100644 index 000000000000..87726a8e394f --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/functions/isIReleaseGroup.md @@ -0,0 +1,25 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / isIReleaseGroup + +# Function: isIReleaseGroup() + +```ts +function isIReleaseGroup(toCheck): toCheck is IReleaseGroup +``` + +A type guard that returns `true` if the checked item is an [IReleaseGroup](../interfaces/IReleaseGroup.md). + +## Parameters + +• **toCheck**: `any` + +## Returns + +`toCheck is IReleaseGroup` + +## Defined in + +[packages/build-infrastructure/src/types.ts:236](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L236) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/FluidPackageJsonFields.md b/build-tools/packages/build-infrastructure/docs/interfaces/FluidPackageJsonFields.md new file mode 100644 index 000000000000..787bdef457a5 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/FluidPackageJsonFields.md @@ -0,0 +1,29 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / FluidPackageJsonFields + +# Interface: FluidPackageJsonFields + +A type representing fluid-build-specific config that may be in package.json. + +## Properties + +### pnpm? + +```ts +optional pnpm: object; +``` + +pnpm config + +#### overrides? + +```ts +optional overrides: Record; +``` + +#### Defined in + +[packages/build-infrastructure/src/types.ts:18](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L18) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IFluidBuildDir.md b/build-tools/packages/build-infrastructure/docs/interfaces/IFluidBuildDir.md new file mode 100644 index 000000000000..ca2a173dcf2d --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IFluidBuildDir.md @@ -0,0 +1,27 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / IFluidBuildDir + +# Interface: ~~IFluidBuildDir~~ + +Configures a package or release group + +## Deprecated + +Use repoLayout and associated types instead. + +## Properties + +### ~~directory~~ + +```ts +directory: string; +``` + +The path to the package. For release groups this should be the path to the root of the release group. + +#### Defined in + +[packages/build-infrastructure/src/config.ts:110](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L110) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IFluidBuildDirs.md b/build-tools/packages/build-infrastructure/docs/interfaces/IFluidBuildDirs.md new file mode 100644 index 000000000000..202fbe43615b --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IFluidBuildDirs.md @@ -0,0 +1,15 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / IFluidBuildDirs + +# Interface: ~~IFluidBuildDirs~~ + +## Deprecated + +Use repoLayout and associated types instead. + +## Indexable + + \[`name`: `string`\]: [`IFluidBuildDirEntry`](../type-aliases/IFluidBuildDirEntry.md) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IFluidRepo.md b/build-tools/packages/build-infrastructure/docs/interfaces/IFluidRepo.md new file mode 100644 index 000000000000..e7ea6c6f8f0f --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IFluidRepo.md @@ -0,0 +1,220 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / IFluidRepo + +# Interface: IFluidRepo\ + +A Fluid repo organizes a collection of npm packages into workspaces and release groups. A Fluid repo can contain +multiple workspaces, and a workspace can in turn contain multiple release groups. Both workspaces and release groups +represent ways to organize packages in the repo, but their purpose and function are different. + +See [IWorkspace](IWorkspace.md) and [IReleaseGroup](IReleaseGroup.md) for more details. + +## Extends + +- [`Reloadable`](Reloadable.md) + +## Type Parameters + +• **P** *extends* [`IPackage`](IPackage.md) = [`IPackage`](IPackage.md) + +## Properties + +### configuration + +```ts +configuration: IFluidRepoLayout; +``` + +The layout configuration for the repo. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:67](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L67) + +*** + +### packages + +```ts +packages: Map; +``` + +A map of all packages in the Fluid repo. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:56](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L56) + +*** + +### releaseGroups + +```ts +releaseGroups: Map; +``` + +A map of all release groups in the Fluid repo. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:51](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L51) + +*** + +### root + +```ts +root: string; +``` + +The absolute path to the root of the IFluidRepo. This is the path where the config file is located. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:41](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L41) + +*** + +### upstreamRemotePartialUrl? + +```ts +optional upstreamRemotePartialUrl: string; +``` + +A partial URL to the upstream (remote) repo. This can be set to the name of the repo on GitHub. For example, +"microsoft/FluidFramework". + +#### Defined in + +[packages/build-infrastructure/src/types.ts:62](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L62) + +*** + +### workspaces + +```ts +workspaces: Map; +``` + +A map of all workspaces in the Fluid repo. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:46](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L46) + +## Methods + +### getGitRepository() + +```ts +getGitRepository(): Promise> +``` + +If the FluidRepo is within a Git repository, this function will return a SimpleGit instance rooted at the root of +the Git repository. If the FluidRepo is _not_ within a Git repository, this function will throw a +[NotInGitRepository](../classes/NotInGitRepository.md) error. + +#### Returns + +`Promise`\<`Readonly`\<`SimpleGit`\>\> + +#### Throws + +A [NotInGitRepository](../classes/NotInGitRepository.md) error if the path is not within a Git repository. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:84](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L84) + +*** + +### getPackageReleaseGroup() + +```ts +getPackageReleaseGroup(pkg): Readonly +``` + +Returns the [IReleaseGroup](IReleaseGroup.md) associated with a package. + +#### Parameters + +• **pkg**: `Readonly`\<`P`\> + +#### Returns + +`Readonly`\<[`IReleaseGroup`](IReleaseGroup.md)\> + +#### Defined in + +[packages/build-infrastructure/src/types.ts:89](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L89) + +*** + +### getPackageWorkspace() + +```ts +getPackageWorkspace(pkg): Readonly +``` + +Returns the [IWorkspace](IWorkspace.md) associated with a package. + +#### Parameters + +• **pkg**: `Readonly`\<`P`\> + +#### Returns + +`Readonly`\<[`IWorkspace`](IWorkspace.md)\> + +#### Defined in + +[packages/build-infrastructure/src/types.ts:94](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L94) + +*** + +### relativeToRepo() + +```ts +relativeToRepo(p): string +``` + +Transforms an absolute path to a path relative to the FluidRepo root. + +#### Parameters + +• **p**: `string` + +The path to make relative to the FluidRepo root. + +#### Returns + +`string` + +the relative path. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:75](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L75) + +*** + +### reload() + +```ts +reload(): void +``` + +#### Returns + +`void` + +#### Inherited from + +[`Reloadable`](Reloadable.md).[`reload`](Reloadable.md#reload) + +#### Defined in + +[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IFluidRepoLayout.md b/build-tools/packages/build-infrastructure/docs/interfaces/IFluidRepoLayout.md new file mode 100644 index 000000000000..ca455a5e704d --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IFluidRepoLayout.md @@ -0,0 +1,67 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / IFluidRepoLayout + +# Interface: IFluidRepoLayout + +Top-most configuration for repo layout settings. + +## Properties + +### repoLayout? + +```ts +optional repoLayout: object; +``` + +The layout of repo into workspaces and release groups. + +#### workspaces + +```ts +workspaces: object; +``` + +##### Index Signature + + \[`name`: `string`\]: [`WorkspaceDefinition`](WorkspaceDefinition.md) + +#### Defined in + +[packages/build-infrastructure/src/config.ts:41](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L41) + +*** + +### ~~repoPackages?~~ + +```ts +optional repoPackages: IFluidBuildDirs; +``` + +**BACK-COMPAT ONLY** + +A mapping of package or release group names to metadata about the package or release group. + +#### Deprecated + +Use the repoLayout property instead. + +#### Defined in + +[packages/build-infrastructure/src/config.ts:36](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L36) + +*** + +### version + +```ts +version: 1; +``` + +The version of the config. + +#### Defined in + +[packages/build-infrastructure/src/config.ts:27](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L27) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IPackage.md b/build-tools/packages/build-infrastructure/docs/interfaces/IPackage.md new file mode 100644 index 000000000000..648055178dbf --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IPackage.md @@ -0,0 +1,336 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / IPackage + +# Interface: IPackage\ + +A common type representing an npm package. A custom type can be used for the package.json schema, which is useful +when the package.json has custom keys/values. + +## Extends + +- [`Installable`](Installable.md).[`Reloadable`](Reloadable.md) + +## Type Parameters + +• **J** *extends* [`PackageJson`](../type-aliases/PackageJson.md) = [`PackageJson`](../type-aliases/PackageJson.md) + +## Properties + +### combinedDependencies + +```ts +combinedDependencies: Generator; +``` + +A generator that returns each dependency and the kind of dependency (dev, peer, etc.) for all of the package's +dependencies. This is useful to iterate overall all dependencies of the package. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:371](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L371) + +*** + +### directory + +```ts +readonly directory: string; +``` + +The absolute path to the directory containing the package (that is, the directory that contains the package.json +for the package). + +#### Defined in + +[packages/build-infrastructure/src/types.ts:302](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L302) + +*** + +### isReleaseGroupRoot + +```ts +isReleaseGroupRoot: boolean; +``` + +Whether the package is a release group root package or not. A release group may not have a root package, but if it +does, it will only have one. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:349](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L349) + +*** + +### isWorkspaceRoot + +```ts +readonly isWorkspaceRoot: boolean; +``` + +Whether the package is a workspace root package or not. A workspace will only have one root package. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:338](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L338) + +*** + +### name + +```ts +readonly name: PackageName; +``` + +The name of the package + +#### Defined in + +[packages/build-infrastructure/src/types.ts:290](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L290) + +*** + +### nameColored + +```ts +readonly nameColored: string; +``` + +The name of the package color-coded with ANSI color codes for terminal output. The package name will always have +the same color. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:296](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L296) + +*** + +### packageJson + +```ts +packageJson: J; +``` + +The package.json contents of the package. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:307](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L307) + +*** + +### packageJsonFilePath + +```ts +readonly packageJsonFilePath: string; +``` + +The absolute path to the package.json file for this package. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:354](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L354) + +*** + +### packageManager + +```ts +readonly packageManager: IPackageManager; +``` + +The package manager used to manage this package. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:317](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L317) + +*** + +### private + +```ts +readonly private: boolean; +``` + +`true` if the package is private; `false` otherwise. This is similar to the field in package.json, but always +returns a boolean value. If the package.json is missing the `private` field, this will return false. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:328](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L328) + +*** + +### releaseGroup + +```ts +releaseGroup: ReleaseGroupName; +``` + +The name of the release group that this package belongs to. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:343](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L343) + +*** + +### version + +```ts +readonly version: string; +``` + +The version of the package. This is the same as `packageJson.version`. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:322](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L322) + +*** + +### workspace + +```ts +readonly workspace: IWorkspace; +``` + +The workspace that this package belongs to. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:333](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L333) + +## Methods + +### checkInstall() + +```ts +checkInstall(): Promise +``` + +Returns `true` if the item is installed. If this returns `false`, then the `install` function can be called to +install. + +#### Returns + +`Promise`\<`boolean`\> + +#### Inherited from + +[`Installable`](Installable.md).[`checkInstall`](Installable.md#checkinstall) + +#### Defined in + +[packages/build-infrastructure/src/types.ts:105](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L105) + +*** + +### getScript() + +```ts +getScript(name): undefined | string +``` + +Returns the value of a script in the package's package.json, or undefined if a script with the provided key is not +found. + +#### Parameters + +• **name**: `string` + +#### Returns + +`undefined` \| `string` + +#### Defined in + +[packages/build-infrastructure/src/types.ts:360](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L360) + +*** + +### install() + +```ts +install(updateLockfile): Promise +``` + +Installs the item. + +#### Parameters + +• **updateLockfile**: `boolean` + +If true, the lockfile will be updated. Otherwise, the lockfile will not be updated. This +may cause the installation to fail. + +#### Returns + +`Promise`\<`boolean`\> + +#### Inherited from + +[`Installable`](Installable.md).[`install`](Installable.md#install) + +#### Defined in + +[packages/build-infrastructure/src/types.ts:113](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L113) + +*** + +### reload() + +```ts +reload(): void +``` + +#### Returns + +`void` + +#### Inherited from + +[`Reloadable`](Reloadable.md).[`reload`](Reloadable.md#reload) + +#### Defined in + +[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) + +*** + +### savePackageJson() + +```ts +savePackageJson(): Promise +``` + +Saves any changes to the packageJson property to the package.json file on disk. + +#### Returns + +`Promise`\<`void`\> + +#### Defined in + +[packages/build-infrastructure/src/types.ts:365](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L365) + +*** + +### toString() + +```ts +toString(): string +``` + +Returns a string representation of an object. + +#### Returns + +`string` + +#### Defined in + +[packages/build-infrastructure/src/types.ts:372](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L372) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IPackageManager.md b/build-tools/packages/build-infrastructure/docs/interfaces/IPackageManager.md new file mode 100644 index 000000000000..377ec95b016c --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IPackageManager.md @@ -0,0 +1,53 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / IPackageManager + +# Interface: IPackageManager + +A package manager, such as "npm" or "pnpm". + +## Properties + +### lockfileName + +```ts +readonly lockfileName: string; +``` + +#### Defined in + +[packages/build-infrastructure/src/types.ts:263](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L263) + +*** + +### name + +```ts +readonly name: PackageManagerName; +``` + +#### Defined in + +[packages/build-infrastructure/src/types.ts:262](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L262) + +## Methods + +### installCommand() + +```ts +installCommand(updateLockfile): string +``` + +#### Parameters + +• **updateLockfile**: `boolean` + +#### Returns + +`string` + +#### Defined in + +[packages/build-infrastructure/src/types.ts:264](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L264) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IReleaseGroup.md b/build-tools/packages/build-infrastructure/docs/interfaces/IReleaseGroup.md new file mode 100644 index 000000000000..047a5ded9638 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IReleaseGroup.md @@ -0,0 +1,608 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / IReleaseGroup + +# Interface: IReleaseGroup + +A release group is a collection of packages that are versioned and released together. All packages within a release +group will have the same version, and all packages will be released at the same time. + +Release groups are not involved in dependency management. They are used for versioning and releasing packages only. +Workspaces, on the other hand, are used to manage dependencies and interdependencies. See [IWorkspace](IWorkspace.md) for more +information. + +## Extends + +- [`Reloadable`](Reloadable.md) + +## Properties + +### adoPipelineUrl? + +```ts +readonly optional adoPipelineUrl: string; +``` + +An optional ADO pipeline URL for the CI pipeline that builds the release group. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:228](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L228) + +*** + +### name + +```ts +readonly name: ReleaseGroupName; +``` + +The name of the release group. All release groups must have unique names. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:196](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L196) + +*** + +### packages + +```ts +readonly packages: IPackage[]; +``` + +An array of all packages in the release group. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:211](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L211) + +*** + +### releaseGroupDependencies + +```ts +readonly releaseGroupDependencies: IReleaseGroup[]; +``` + +An array of all the release groups that the release group depends on. If any package in a release group has any +dependency on a package in another release group within the same workspace, then the first release group depends +on the second. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:223](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L223) + +*** + +### rootPackage? + +```ts +readonly optional rootPackage: IPackage; +``` + +The package that is the release group root, if one exists. + +#### Type declaration + +##### author? + +```ts +optional author: Person; +``` + +##### bin? + +```ts +optional bin: string | Partial>; +``` + +The executable files that should be installed into the `PATH`. + +##### browser? + +```ts +optional browser: string | Partial>; +``` + +A hint to JavaScript bundlers or component tools when packaging modules for client side use. + +##### bugs? + +```ts +optional bugs: BugsLocation; +``` + +The URL to the package's issue tracker and/or the email address to which issues should be reported. + +##### bundledDependencies? + +```ts +optional bundledDependencies: string[]; +``` + +Package names that are bundled when the package is published. + +##### bundleDependencies? + +```ts +optional bundleDependencies: string[]; +``` + +Alias of `bundledDependencies`. + +##### config? + +```ts +optional config: Record; +``` + +Is used to set configuration parameters used in package scripts that persist across upgrades. + +##### contributors? + +```ts +optional contributors: Person[]; +``` + +A list of people who contributed to the package. + +##### cpu? + +```ts +optional cpu: LiteralUnion< + | "arm" + | "arm64" + | "ia32" + | "mips" + | "mipsel" + | "ppc" + | "ppc64" + | "s390" + | "s390x" + | "x64" + | "x32" + | "!arm" + | "!arm64" + | "!ia32" + | "!mips" + | "!mipsel" + | "!ppc" + | "!ppc64" + | "!s390" + | "!s390x" + | "!x32" + | "!x64", string>[]; +``` + +CPU architectures the module runs on. + +##### dependencies? + +```ts +optional dependencies: Partial>; +``` + +The dependencies of the package. + +##### description? + +```ts +optional description: string; +``` + +Package description, listed in `npm search`. + +##### devDependencies? + +```ts +optional devDependencies: Partial>; +``` + +Additional tooling dependencies that are not required for the package to work. Usually test, build, or documentation tooling. + +##### directories? + +```ts +optional directories: DirectoryLocations; +``` + +Indicates the structure of the package. + +##### engines? + +```ts +optional engines: object; +``` + +Engines that this package runs on. + +##### ~~engineStrict?~~ + +```ts +optional engineStrict: boolean; +``` + +###### Deprecated + +##### esnext? + +```ts +optional esnext: string | object; +``` + +A module ID with untranspiled code that is the primary entry point to the program. + +##### exports? + +```ts +optional exports: Exports; +``` + +Subpath exports to define entry points of the package. + +[Read more.](https://nodejs.org/api/packages.html#subpath-exports) + +##### files? + +```ts +optional files: string[]; +``` + +The files included in the package. + +##### flat? + +```ts +optional flat: boolean; +``` + +If your package only allows one version of a given dependency, and you’d like to enforce the same behavior as `yarn install --flat` on the command-line, set this to `true`. + +Note that if your `package.json` contains `"flat": true` and other packages depend on yours (e.g. you are building a library rather than an app), those other packages will also need `"flat": true` in their `package.json` or be installed with `yarn install --flat` on the command-line. + +##### funding? + +```ts +optional funding: string | object; +``` + +Describes and notifies consumers of a package's monetary support information. + +[Read more.](https://github.com/npm/rfcs/blob/latest/accepted/0017-add-funding-support.md) + +##### homepage? + +```ts +optional homepage: LiteralUnion<".", string>; +``` + +The URL to the package's homepage. + +##### imports? + +```ts +optional imports: Imports; +``` + +Subpath imports to define internal package import maps that only apply to import specifiers from within the package itself. + +[Read more.](https://nodejs.org/api/packages.html#subpath-imports) + +##### jspm? + +```ts +optional jspm: PackageJson; +``` + +JSPM configuration. + +##### keywords? + +```ts +optional keywords: string[]; +``` + +Keywords associated with package, listed in `npm search`. + +##### license? + +```ts +optional license: string; +``` + +The license for the package. + +##### licenses? + +```ts +optional licenses: object[]; +``` + +The licenses for the package. + +##### main? + +```ts +optional main: string; +``` + +The module ID that is the primary entry point to the program. + +##### maintainers? + +```ts +optional maintainers: Person[]; +``` + +A list of people who maintain the package. + +##### man? + +```ts +optional man: string | string[]; +``` + +Filenames to put in place for the `man` program to find. + +##### module? + +```ts +optional module: string; +``` + +An ECMAScript module ID that is the primary entry point to the program. + +##### name + +```ts +name: string; +``` + +The name of the package. + +##### optionalDependencies? + +```ts +optional optionalDependencies: Partial>; +``` + +Dependencies that are skipped if they fail to install. + +##### os? + +```ts +optional os: LiteralUnion< + | "aix" + | "darwin" + | "freebsd" + | "linux" + | "openbsd" + | "sunos" + | "win32" + | "!aix" + | "!darwin" + | "!freebsd" + | "!linux" + | "!openbsd" + | "!sunos" + | "!win32", string>[]; +``` + +Operating systems the module runs on. + +##### peerDependencies? + +```ts +optional peerDependencies: Partial>; +``` + +Dependencies that will usually be required by the package user directly or via another dependency. + +##### peerDependenciesMeta? + +```ts +optional peerDependenciesMeta: Partial>; +``` + +Indicate peer dependencies that are optional. + +##### pnpm? + +```ts +optional pnpm: object; +``` + +pnpm config + +##### pnpm.overrides? + +```ts +optional overrides: Record; +``` + +##### ~~preferGlobal?~~ + +```ts +optional preferGlobal: boolean; +``` + +If set to `true`, a warning will be shown if package is installed locally. Useful if the package is primarily a command-line application that should be installed globally. + +###### Deprecated + +##### private? + +```ts +optional private: boolean; +``` + +If set to `true`, then npm will refuse to publish it. + +##### publishConfig? + +```ts +optional publishConfig: PublishConfig; +``` + +A set of config values that will be used at publish-time. It's especially handy to set the tag, registry or access, to ensure that a given package is not tagged with 'latest', published to the global public registry or that a scoped module is private by default. + +##### repository? + +```ts +optional repository: string | object; +``` + +Location for the code repository. + +##### resolutions? + +```ts +optional resolutions: Partial>; +``` + +Selective version resolutions. Allows the definition of custom package versions inside dependencies without manual edits in the `yarn.lock` file. + +##### scripts + +```ts +scripts: Scripts; +``` + +Script commands that are run at various times in the lifecycle of the package. The key is the lifecycle event, and the value is the command to run at that point. + +##### sideEffects? + +```ts +optional sideEffects: boolean | string[]; +``` + +Denote which files in your project are "pure" and therefore safe for Webpack to prune if unused. + +[Read more.](https://webpack.js.org/guides/tree-shaking/) + +##### type? + +```ts +optional type: "module" | "commonjs"; +``` + +Resolution algorithm for importing ".js" files from the package's scope. + +[Read more.](https://nodejs.org/api/esm.html#esm_package_json_type_field) + +##### types? + +```ts +optional types: string; +``` + +Location of the bundled TypeScript declaration file. + +##### typesVersions? + +```ts +optional typesVersions: Partial>>>; +``` + +Version selection map of TypeScript. + +##### typings? + +```ts +optional typings: string; +``` + +Location of the bundled TypeScript declaration file. Alias of `types`. + +##### version + +```ts +version: string; +``` + +Package version, parseable by [`node-semver`](https://github.com/npm/node-semver). + +##### workspaces? + +```ts +optional workspaces: string[] | WorkspaceConfig; +``` + +Used to configure [Yarn workspaces](https://classic.yarnpkg.com/docs/workspaces/). + +Workspaces allow you to manage multiple packages within the same repository in such a way that you only need to run `yarn install` once to install all of them in a single pass. + +Please note that the top-level `private` property of `package.json` **must** be set to `true` in order to use workspaces. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:206](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L206) + +*** + +### version + +```ts +readonly version: string; +``` + +The version of the release group. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:201](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L201) + +*** + +### workspace + +```ts +readonly workspace: IWorkspace; +``` + +The workspace that the release group belongs to. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:216](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L216) + +## Methods + +### reload() + +```ts +reload(): void +``` + +#### Returns + +`void` + +#### Inherited from + +[`Reloadable`](Reloadable.md).[`reload`](Reloadable.md#reload) + +#### Defined in + +[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) + +*** + +### toString() + +```ts +toString(): string +``` + +Returns a string representation of an object. + +#### Returns + +`string` + +#### Defined in + +[packages/build-infrastructure/src/types.ts:230](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L230) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IWorkspace.md b/build-tools/packages/build-infrastructure/docs/interfaces/IWorkspace.md new file mode 100644 index 000000000000..3f210f919757 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IWorkspace.md @@ -0,0 +1,645 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / IWorkspace + +# Interface: IWorkspace + +A workspace is a collection of packages, including a root package, that is managed using a package manager's +"workspaces" functionality. A Fluid repo can contain multiple workspaces. Workspaces are defined and managed using +the package manager directly. A Fluid repo builds on top of workspaces and relies on the package manager to install +and manage dependencies and interdependencies within the workspace. + +A workspace defines the _physical layout_ of the packages within it. Workspaces are a generally a feature provided by +the package manager (npm, yarn, pnpm, etc.). A workspace is rooted in a particular folder, and uses the configuration +within that folder to determine what packages it contains. The configuration used is specific to the package manager. + +The workspace is also the boundary at which dependencies are installed and managed. When you install dependencies for +a package in a workspace, all dependencies for all packages in the workspace will be installed. Within a workspace, +it is trivial to link multiple packages so they can depend on one another. The `IWorkspace` type is a thin wrapper on +top of these package manager features. + +A Fluid repo will only load packages identified by the package manager's workspace feature. That is, any package in +the repo that is not configured as part of a workspace is invisible to tools using the Fluid repo. + +Workspaces are not involved in versioning or releasing packages. They are used for dependency management only. +Release groups, on the other hand, are used to group packages into releasable groups. See [IReleaseGroup](IReleaseGroup.md) for +more information. + +## Extends + +- [`Installable`](Installable.md).[`Reloadable`](Reloadable.md) + +## Properties + +### directory + +```ts +directory: string; +``` + +The root directory of the workspace. This directory will contain the workspace root package. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:159](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L159) + +*** + +### name + +```ts +name: WorkspaceName; +``` + +The name of the workspace. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:154](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L154) + +*** + +### packages + +```ts +packages: IPackage[]; +``` + +An array of all the packages in the workspace. This includes the workspace root and any release group roots and +constituent packages as well. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:175](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L175) + +*** + +### releaseGroups + +```ts +releaseGroups: Map; +``` + +A map of all the release groups in the workspace. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:169](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L169) + +*** + +### rootPackage + +```ts +rootPackage: IPackage; +``` + +The root package of the workspace. + +#### Type declaration + +##### author? + +```ts +optional author: Person; +``` + +##### bin? + +```ts +optional bin: string | Partial>; +``` + +The executable files that should be installed into the `PATH`. + +##### browser? + +```ts +optional browser: string | Partial>; +``` + +A hint to JavaScript bundlers or component tools when packaging modules for client side use. + +##### bugs? + +```ts +optional bugs: BugsLocation; +``` + +The URL to the package's issue tracker and/or the email address to which issues should be reported. + +##### bundledDependencies? + +```ts +optional bundledDependencies: string[]; +``` + +Package names that are bundled when the package is published. + +##### bundleDependencies? + +```ts +optional bundleDependencies: string[]; +``` + +Alias of `bundledDependencies`. + +##### config? + +```ts +optional config: Record; +``` + +Is used to set configuration parameters used in package scripts that persist across upgrades. + +##### contributors? + +```ts +optional contributors: Person[]; +``` + +A list of people who contributed to the package. + +##### cpu? + +```ts +optional cpu: LiteralUnion< + | "arm" + | "arm64" + | "ia32" + | "mips" + | "mipsel" + | "ppc" + | "ppc64" + | "s390" + | "s390x" + | "x64" + | "x32" + | "!arm" + | "!arm64" + | "!ia32" + | "!mips" + | "!mipsel" + | "!ppc" + | "!ppc64" + | "!s390" + | "!s390x" + | "!x32" + | "!x64", string>[]; +``` + +CPU architectures the module runs on. + +##### dependencies? + +```ts +optional dependencies: Partial>; +``` + +The dependencies of the package. + +##### description? + +```ts +optional description: string; +``` + +Package description, listed in `npm search`. + +##### devDependencies? + +```ts +optional devDependencies: Partial>; +``` + +Additional tooling dependencies that are not required for the package to work. Usually test, build, or documentation tooling. + +##### directories? + +```ts +optional directories: DirectoryLocations; +``` + +Indicates the structure of the package. + +##### engines? + +```ts +optional engines: object; +``` + +Engines that this package runs on. + +##### ~~engineStrict?~~ + +```ts +optional engineStrict: boolean; +``` + +###### Deprecated + +##### esnext? + +```ts +optional esnext: string | object; +``` + +A module ID with untranspiled code that is the primary entry point to the program. + +##### exports? + +```ts +optional exports: Exports; +``` + +Subpath exports to define entry points of the package. + +[Read more.](https://nodejs.org/api/packages.html#subpath-exports) + +##### files? + +```ts +optional files: string[]; +``` + +The files included in the package. + +##### flat? + +```ts +optional flat: boolean; +``` + +If your package only allows one version of a given dependency, and you’d like to enforce the same behavior as `yarn install --flat` on the command-line, set this to `true`. + +Note that if your `package.json` contains `"flat": true` and other packages depend on yours (e.g. you are building a library rather than an app), those other packages will also need `"flat": true` in their `package.json` or be installed with `yarn install --flat` on the command-line. + +##### funding? + +```ts +optional funding: string | object; +``` + +Describes and notifies consumers of a package's monetary support information. + +[Read more.](https://github.com/npm/rfcs/blob/latest/accepted/0017-add-funding-support.md) + +##### homepage? + +```ts +optional homepage: LiteralUnion<".", string>; +``` + +The URL to the package's homepage. + +##### imports? + +```ts +optional imports: Imports; +``` + +Subpath imports to define internal package import maps that only apply to import specifiers from within the package itself. + +[Read more.](https://nodejs.org/api/packages.html#subpath-imports) + +##### jspm? + +```ts +optional jspm: PackageJson; +``` + +JSPM configuration. + +##### keywords? + +```ts +optional keywords: string[]; +``` + +Keywords associated with package, listed in `npm search`. + +##### license? + +```ts +optional license: string; +``` + +The license for the package. + +##### licenses? + +```ts +optional licenses: object[]; +``` + +The licenses for the package. + +##### main? + +```ts +optional main: string; +``` + +The module ID that is the primary entry point to the program. + +##### maintainers? + +```ts +optional maintainers: Person[]; +``` + +A list of people who maintain the package. + +##### man? + +```ts +optional man: string | string[]; +``` + +Filenames to put in place for the `man` program to find. + +##### module? + +```ts +optional module: string; +``` + +An ECMAScript module ID that is the primary entry point to the program. + +##### name + +```ts +name: string; +``` + +The name of the package. + +##### optionalDependencies? + +```ts +optional optionalDependencies: Partial>; +``` + +Dependencies that are skipped if they fail to install. + +##### os? + +```ts +optional os: LiteralUnion< + | "aix" + | "darwin" + | "freebsd" + | "linux" + | "openbsd" + | "sunos" + | "win32" + | "!aix" + | "!darwin" + | "!freebsd" + | "!linux" + | "!openbsd" + | "!sunos" + | "!win32", string>[]; +``` + +Operating systems the module runs on. + +##### peerDependencies? + +```ts +optional peerDependencies: Partial>; +``` + +Dependencies that will usually be required by the package user directly or via another dependency. + +##### peerDependenciesMeta? + +```ts +optional peerDependenciesMeta: Partial>; +``` + +Indicate peer dependencies that are optional. + +##### pnpm? + +```ts +optional pnpm: object; +``` + +pnpm config + +##### pnpm.overrides? + +```ts +optional overrides: Record; +``` + +##### ~~preferGlobal?~~ + +```ts +optional preferGlobal: boolean; +``` + +If set to `true`, a warning will be shown if package is installed locally. Useful if the package is primarily a command-line application that should be installed globally. + +###### Deprecated + +##### private? + +```ts +optional private: boolean; +``` + +If set to `true`, then npm will refuse to publish it. + +##### publishConfig? + +```ts +optional publishConfig: PublishConfig; +``` + +A set of config values that will be used at publish-time. It's especially handy to set the tag, registry or access, to ensure that a given package is not tagged with 'latest', published to the global public registry or that a scoped module is private by default. + +##### repository? + +```ts +optional repository: string | object; +``` + +Location for the code repository. + +##### resolutions? + +```ts +optional resolutions: Partial>; +``` + +Selective version resolutions. Allows the definition of custom package versions inside dependencies without manual edits in the `yarn.lock` file. + +##### scripts + +```ts +scripts: Scripts; +``` + +Script commands that are run at various times in the lifecycle of the package. The key is the lifecycle event, and the value is the command to run at that point. + +##### sideEffects? + +```ts +optional sideEffects: boolean | string[]; +``` + +Denote which files in your project are "pure" and therefore safe for Webpack to prune if unused. + +[Read more.](https://webpack.js.org/guides/tree-shaking/) + +##### type? + +```ts +optional type: "module" | "commonjs"; +``` + +Resolution algorithm for importing ".js" files from the package's scope. + +[Read more.](https://nodejs.org/api/esm.html#esm_package_json_type_field) + +##### types? + +```ts +optional types: string; +``` + +Location of the bundled TypeScript declaration file. + +##### typesVersions? + +```ts +optional typesVersions: Partial>>>; +``` + +Version selection map of TypeScript. + +##### typings? + +```ts +optional typings: string; +``` + +Location of the bundled TypeScript declaration file. Alias of `types`. + +##### version + +```ts +version: string; +``` + +Package version, parseable by [`node-semver`](https://github.com/npm/node-semver). + +##### workspaces? + +```ts +optional workspaces: string[] | WorkspaceConfig; +``` + +Used to configure [Yarn workspaces](https://classic.yarnpkg.com/docs/workspaces/). + +Workspaces allow you to manage multiple packages within the same repository in such a way that you only need to run `yarn install` once to install all of them in a single pass. + +Please note that the top-level `private` property of `package.json` **must** be set to `true` in order to use workspaces. + +#### Defined in + +[packages/build-infrastructure/src/types.ts:164](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L164) + +## Methods + +### checkInstall() + +```ts +checkInstall(): Promise +``` + +Returns `true` if the item is installed. If this returns `false`, then the `install` function can be called to +install. + +#### Returns + +`Promise`\<`boolean`\> + +#### Inherited from + +[`Installable`](Installable.md).[`checkInstall`](Installable.md#checkinstall) + +#### Defined in + +[packages/build-infrastructure/src/types.ts:105](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L105) + +*** + +### install() + +```ts +install(updateLockfile): Promise +``` + +Installs the item. + +#### Parameters + +• **updateLockfile**: `boolean` + +If true, the lockfile will be updated. Otherwise, the lockfile will not be updated. This +may cause the installation to fail. + +#### Returns + +`Promise`\<`boolean`\> + +#### Inherited from + +[`Installable`](Installable.md).[`install`](Installable.md#install) + +#### Defined in + +[packages/build-infrastructure/src/types.ts:113](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L113) + +*** + +### reload() + +```ts +reload(): void +``` + +#### Returns + +`void` + +#### Inherited from + +[`Reloadable`](Reloadable.md).[`reload`](Reloadable.md#reload) + +#### Defined in + +[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) + +*** + +### toString() + +```ts +toString(): string +``` + +Returns a string representation of an object. + +#### Returns + +`string` + +#### Defined in + +[packages/build-infrastructure/src/types.ts:176](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L176) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/Installable.md b/build-tools/packages/build-infrastructure/docs/interfaces/Installable.md new file mode 100644 index 000000000000..0c8fcc83fe58 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/Installable.md @@ -0,0 +1,58 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / Installable + +# Interface: Installable + +A common interface for installable things, like packages, release groups, and workspaces. + +## Extended by + +- [`IPackage`](IPackage.md) +- [`IWorkspace`](IWorkspace.md) + +## Methods + +### checkInstall() + +```ts +checkInstall(): Promise +``` + +Returns `true` if the item is installed. If this returns `false`, then the `install` function can be called to +install. + +#### Returns + +`Promise`\<`boolean`\> + +#### Defined in + +[packages/build-infrastructure/src/types.ts:105](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L105) + +*** + +### install() + +```ts +install(updateLockfile): Promise +``` + +Installs the item. + +#### Parameters + +• **updateLockfile**: `boolean` + +If true, the lockfile will be updated. Otherwise, the lockfile will not be updated. This +may cause the installation to fail. + +#### Returns + +`Promise`\<`boolean`\> + +#### Defined in + +[packages/build-infrastructure/src/types.ts:113](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L113) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/PackageDependency.md b/build-tools/packages/build-infrastructure/docs/interfaces/PackageDependency.md new file mode 100644 index 000000000000..84dd47392595 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/PackageDependency.md @@ -0,0 +1,45 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / PackageDependency + +# Interface: PackageDependency + +Information about a package dependency. + +## Properties + +### depClass + +```ts +depClass: "prod" | "dev" | "peer"; +``` + +#### Defined in + +[packages/build-infrastructure/src/types.ts:272](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L272) + +*** + +### name + +```ts +name: PackageName; +``` + +#### Defined in + +[packages/build-infrastructure/src/types.ts:270](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L270) + +*** + +### version + +```ts +version: string; +``` + +#### Defined in + +[packages/build-infrastructure/src/types.ts:271](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L271) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/ReleaseGroupDefinition.md b/build-tools/packages/build-infrastructure/docs/interfaces/ReleaseGroupDefinition.md new file mode 100644 index 000000000000..b04a3a62d7b7 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/ReleaseGroupDefinition.md @@ -0,0 +1,72 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / ReleaseGroupDefinition + +# Interface: ReleaseGroupDefinition + +## Properties + +### adoPipelineUrl? + +```ts +optional adoPipelineUrl: string; +``` + +A URL to the ADO CI pipeline that builds the release group. + +#### Defined in + +[packages/build-infrastructure/src/config.ts:86](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L86) + +*** + +### exclude? + +```ts +optional exclude: string[]; +``` + +An array of scopes or package names that should be excluded. Exclusions are applied AFTER inclusions, so +this can be used to exclude specific packages in a certain scope. + +#### Defined in + +[packages/build-infrastructure/src/config.ts:69](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L69) + +*** + +### include + +```ts +include: string[]; +``` + +An array of scopes or package names that should be included in the release group. Each package must +belong to a single release group. + +#### Defined in + +[packages/build-infrastructure/src/config.ts:63](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L63) + +*** + +### rootPackageName? + +```ts +optional rootPackageName: string; +``` + +The name of the package that should be considered the root package for the release group. If not provided, the +release group is considered "rootless." + +#### Remarks + +A release group may have a "root package" that is part of the workspace but fills a similar role to the +workspace-root package: it is a convenient place to store release-group-wide scripts as opposed to workspace-wide +scripts. + +#### Defined in + +[packages/build-infrastructure/src/config.ts:81](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L81) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/Reloadable.md b/build-tools/packages/build-infrastructure/docs/interfaces/Reloadable.md new file mode 100644 index 000000000000..b9fe91a7bbde --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/Reloadable.md @@ -0,0 +1,32 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / Reloadable + +# Interface: Reloadable + +An interface for things that can be reloaded, + +## Extended by + +- [`IFluidRepo`](IFluidRepo.md) +- [`IPackage`](IPackage.md) +- [`IReleaseGroup`](IReleaseGroup.md) +- [`IWorkspace`](IWorkspace.md) + +## Methods + +### reload() + +```ts +reload(): void +``` + +#### Returns + +`void` + +#### Defined in + +[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/WorkspaceDefinition.md b/build-tools/packages/build-infrastructure/docs/interfaces/WorkspaceDefinition.md new file mode 100644 index 000000000000..c598c08ad917 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/interfaces/WorkspaceDefinition.md @@ -0,0 +1,35 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / WorkspaceDefinition + +# Interface: WorkspaceDefinition + +## Properties + +### directory + +```ts +directory: string; +``` + +#### Defined in + +[packages/build-infrastructure/src/config.ts:52](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L52) + +*** + +### releaseGroups + +```ts +releaseGroups: object; +``` + +#### Index Signature + + \[`name`: `string`\]: [`ReleaseGroupDefinition`](ReleaseGroupDefinition.md) + +#### Defined in + +[packages/build-infrastructure/src/config.ts:53](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L53) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/AdditionalPackageProps.md b/build-tools/packages/build-infrastructure/docs/type-aliases/AdditionalPackageProps.md new file mode 100644 index 000000000000..238ba591cbe0 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/AdditionalPackageProps.md @@ -0,0 +1,15 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / AdditionalPackageProps + +# Type Alias: AdditionalPackageProps + +```ts +type AdditionalPackageProps: Record | undefined; +``` + +## Defined in + +[packages/build-infrastructure/src/types.ts:28](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L28) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/IFluidBuildDirEntry.md b/build-tools/packages/build-infrastructure/docs/type-aliases/IFluidBuildDirEntry.md new file mode 100644 index 000000000000..94dcedf645ec --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/IFluidBuildDirEntry.md @@ -0,0 +1,19 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / IFluidBuildDirEntry + +# Type Alias: ~~IFluidBuildDirEntry~~ + +```ts +type IFluidBuildDirEntry: string | IFluidBuildDir | (string | IFluidBuildDir)[]; +``` + +## Deprecated + +Use repoLayout and associated types instead. + +## Defined in + +[packages/build-infrastructure/src/config.ts:99](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L99) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/PackageJson.md b/build-tools/packages/build-infrastructure/docs/type-aliases/PackageJson.md new file mode 100644 index 000000000000..4233d5b0a31f --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/PackageJson.md @@ -0,0 +1,15 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / PackageJson + +# Type Alias: PackageJson + +```ts +type PackageJson: SetRequired; +``` + +## Defined in + +[packages/build-infrastructure/src/types.ts:23](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L23) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/PackageManagerName.md b/build-tools/packages/build-infrastructure/docs/type-aliases/PackageManagerName.md new file mode 100644 index 000000000000..edf9d6a3fd91 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/PackageManagerName.md @@ -0,0 +1,17 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / PackageManagerName + +# Type Alias: PackageManagerName + +```ts +type PackageManagerName: "npm" | "pnpm" | "yarn"; +``` + +Known package managers supported by build-infrastructure. + +## Defined in + +[packages/build-infrastructure/src/types.ts:256](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L256) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/PackageName.md b/build-tools/packages/build-infrastructure/docs/type-aliases/PackageName.md new file mode 100644 index 000000000000..0287be8e6fc2 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/PackageName.md @@ -0,0 +1,17 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / PackageName + +# Type Alias: PackageName + +```ts +type PackageName: Opaque; +``` + +A tagged type representing package names. + +## Defined in + +[packages/build-infrastructure/src/types.ts:278](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L278) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/ReleaseGroupName.md b/build-tools/packages/build-infrastructure/docs/type-aliases/ReleaseGroupName.md new file mode 100644 index 000000000000..15e23ca4e227 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/ReleaseGroupName.md @@ -0,0 +1,17 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / ReleaseGroupName + +# Type Alias: ReleaseGroupName + +```ts +type ReleaseGroupName: Opaque; +``` + +A tagged type representing release group names. + +## Defined in + +[packages/build-infrastructure/src/types.ts:182](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L182) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/WorkspaceName.md b/build-tools/packages/build-infrastructure/docs/type-aliases/WorkspaceName.md new file mode 100644 index 000000000000..d03d90550f1c --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/WorkspaceName.md @@ -0,0 +1,17 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / WorkspaceName + +# Type Alias: WorkspaceName + +```ts +type WorkspaceName: Opaque; +``` + +A tagged type representing workspace names. + +## Defined in + +[packages/build-infrastructure/src/types.ts:126](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L126) diff --git a/build-tools/packages/build-infrastructure/docs/variables/FLUIDREPO_CONFIG_VERSION.md b/build-tools/packages/build-infrastructure/docs/variables/FLUIDREPO_CONFIG_VERSION.md new file mode 100644 index 000000000000..ae73d1f09932 --- /dev/null +++ b/build-tools/packages/build-infrastructure/docs/variables/FLUIDREPO_CONFIG_VERSION.md @@ -0,0 +1,17 @@ +[**@fluid-tools/build-infrastructure**](../README.md) • **Docs** + +*** + +[@fluid-tools/build-infrastructure](../README.md) / FLUIDREPO\_CONFIG\_VERSION + +# Variable: FLUIDREPO\_CONFIG\_VERSION + +```ts +const FLUIDREPO_CONFIG_VERSION: 1 = 1; +``` + +The version of the fluidRepo configuration currently used. + +## Defined in + +[packages/build-infrastructure/src/config.ts:18](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L18) diff --git a/build-tools/packages/build-infrastructure/mocha-multi-reporter-config.json b/build-tools/packages/build-infrastructure/mocha-multi-reporter-config.json new file mode 100644 index 000000000000..5e47c5accce7 --- /dev/null +++ b/build-tools/packages/build-infrastructure/mocha-multi-reporter-config.json @@ -0,0 +1,6 @@ +{ + "reporterEnabled": "xunit,spec", + "xunitReporterOptions": { + "output": "nyc/junit-report.xml" + } +} diff --git a/build-tools/packages/build-infrastructure/package.json b/build-tools/packages/build-infrastructure/package.json new file mode 100644 index 000000000000..0758e67d2bc8 --- /dev/null +++ b/build-tools/packages/build-infrastructure/package.json @@ -0,0 +1,126 @@ +{ + "name": "@fluid-tools/build-infrastructure", + "version": "0.45.0", + "private": true, + "description": "Fluid build infrastructure", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure" + }, + "license": "MIT", + "author": "Microsoft and contributors", + "type": "module", + "exports": { + ".": { + "import": { + "types": "./lib/index.d.ts", + "default": "./lib/index.js" + }, + "require": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + } + } + }, + "main": "lib/index.js", + "bin": { + "repo-layout": "./bin/run.mjs" + }, + "files": [ + "/bin", + "/dist", + "!dist/test", + "/lib", + "!lib/test", + "/oclif.manifest.json" + ], + "scripts": { + "build": "fluid-build . --task build", + "build:commonjs": "npm run tsc && npm run build:test", + "build:compile": "npm run build:commonjs", + "build:docs": "api-extractor run --local && typedoc", + "build:esnext": "tsc --project ./tsconfig.json", + "build:manifest": "oclif manifest", + "build:test": "npm run build:test:esm && npm run build:test:cjs", + "build:test:cjs": "fluid-tsc commonjs --project ./src/test/tsconfig.cjs.json", + "build:test:esm": "tsc --project ./src/test/tsconfig.json", + "check:biome": "biome check .", + "check:format": "npm run check:biome", + "clean": "rimraf --glob dist lib \"**/*.tsbuildinfo\" \"**/*.build.log\" nyc _api-extractor-temp", + "compile": "fluid-build . --task compile", + "eslint": "eslint --format stylish src", + "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout", + "format": "npm run format:biome", + "format:biome": "biome check --write .", + "lint": "npm run eslint", + "lint:fix": "npm run eslint:fix", + "test": "npm run test:mocha", + "test:coverage": "c8 npm run test", + "test:mocha": "mocha --recursive lib/test", + "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist" + }, + "dependencies": { + "@fluid-tools/version-tools": "workspace:^", + "@manypkg/get-packages": "^2.2.0", + "@oclif/core": "^4.0.14", + "cosmiconfig": "^8.3.6", + "detect-indent": "^6.1.0", + "execa": "^5.1.1", + "fs-extra": "^11.2.0", + "globby": "^11.1.0", + "micromatch": "^4.0.8", + "oclif": "^4.14.9", + "picocolors": "^1.1.0", + "read-pkg-up": "^7.0.1", + "semver": "^7.5.4", + "simple-git": "^3.19.1", + "sort-package-json": "1.57.0", + "type-fest": "^2.19.0", + "typescript": "~5.4.5" + }, + "devDependencies": { + "@biomejs/biome": "~1.9.3", + "@fluid-tools/api-markdown-documenter": "^0.17.1", + "@fluidframework/build-common": "^2.0.3", + "@fluidframework/build-tools-bin": "npm:@fluidframework/build-tools@~0.44.0", + "@fluidframework/eslint-config-fluid": "^5.3.0", + "@microsoft/api-extractor": "^7.45.1", + "@types/chai": "^4.3.5", + "@types/chai-arrays": "^2.0.0", + "@types/fs-extra": "^11.0.4", + "@types/micromatch": "^4.0.9", + "@types/mocha": "^9.1.1", + "@types/node": "^18.18.6", + "@types/semver": "^7.5.0", + "c8": "^7.14.0", + "chai": "^4.3.7", + "chai-arrays": "^2.2.0", + "concurrently": "^8.2.1", + "copyfiles": "^2.4.1", + "eslint": "~8.57.0", + "eslint-plugin-chai-friendly": "~1.0.1", + "memfs": "^4.14.0", + "mocha": "^10.2.0", + "rimraf": "^4.4.1", + "ts-node": "^10.9.1", + "typedoc": "^0.26.10", + "typedoc-plugin-markdown": "^4.2.9", + "unionfs": "^4.5.4" + }, + "oclif": { + "bin": "repo-layout", + "dirname": "repo-layout", + "commands": "./lib/commands", + "additionalHelpFlags": [ + "-h" + ], + "additionalVersionFlags": [ + "-V" + ], + "plugins": [], + "repositoryPrefix": "<%- repo %>/blob/main/build-tools/packages/build-infrastructure/<%- commandPath %>", + "topicSeparator": " " + } +} diff --git a/build-tools/packages/build-infrastructure/src/config.ts b/build-tools/packages/build-infrastructure/src/config.ts new file mode 100644 index 000000000000..d046fea3558b --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/config.ts @@ -0,0 +1,220 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +import { cosmiconfigSync } from "cosmiconfig"; + +import { + type IPackage, + type PackageName, + type ReleaseGroupName, + isIPackage, +} from "./types.js"; + +/** + * The version of the fluidRepo configuration currently used. + */ +export const FLUIDREPO_CONFIG_VERSION = 1; + +/** + * Top-most configuration for repo layout settings. + */ +export interface IFluidRepoLayout { + /** + * The version of the config. + */ + version: typeof FLUIDREPO_CONFIG_VERSION; + + /** + * **BACK-COMPAT ONLY** + * + * A mapping of package or release group names to metadata about the package or release group. + * + * @deprecated Use the repoLayout property instead. + */ + repoPackages?: IFluidBuildDirs; + + /** + * The layout of repo into workspaces and release groups. + */ + repoLayout?: { + workspaces: { + /** + * A mapping of workspace name to folder containing a workspace config file (e.g. pnpm-workspace.yaml) + */ + [name: string]: WorkspaceDefinition; + }; + }; +} + +export interface WorkspaceDefinition { + directory: string; + releaseGroups: { + [name: string]: ReleaseGroupDefinition; + }; +} + +export interface ReleaseGroupDefinition { + /** + * An array of scopes or package names that should be included in the release group. Each package must + * belong to a single release group. + */ + include: string[]; + + /** + * An array of scopes or package names that should be excluded. Exclusions are applied AFTER inclusions, so + * this can be used to exclude specific packages in a certain scope. + */ + exclude?: string[]; + + /** + * The name of the package that should be considered the root package for the release group. If not provided, the + * release group is considered "rootless." + * + * @remarks + * + * A release group may have a "root package" that is part of the workspace but fills a similar role to the + * workspace-root package: it is a convenient place to store release-group-wide scripts as opposed to workspace-wide + * scripts. + */ + rootPackageName?: string; + + /** + * A URL to the ADO CI pipeline that builds the release group. + */ + adoPipelineUrl?: string; +} + +/** + * @deprecated Use repoLayout and associated types instead. + */ +export interface IFluidBuildDirs { + [name: string]: IFluidBuildDirEntry; +} + +/** + * @deprecated Use repoLayout and associated types instead. + */ +export type IFluidBuildDirEntry = string | IFluidBuildDir | (string | IFluidBuildDir)[]; + +/** + * Configures a package or release group + * + * @deprecated Use repoLayout and associated types instead. + */ +export interface IFluidBuildDir { + /** + * The path to the package. For release groups this should be the path to the root of the release group. + */ + directory: string; + + /** + * An array of paths under `directory` that should be ignored. + */ + // ignoredDirs?: string[]; +} + +/** + * Checks if a package matches a given release group definition. + * + * @returns `true` if the package matches the release group definition; `false` otherwise. + */ +export function matchesReleaseGroupDefinition( + pkg: IPackage | PackageName, + { include, exclude, rootPackageName }: ReleaseGroupDefinition, +): boolean { + const name = isIPackage(pkg) ? pkg.name : pkg; + let shouldInclude = false; + + if ( + // Special case: include with a single element, "*", should include all packages. + (include.length === 1 && include[0] === "*") || + // If the package name matches an entry in the include list, it should be included + include.includes(name) || + // If the package name starts with any of the include list entries, it should be included + include.some((scope) => name.startsWith(scope)) + ) { + shouldInclude = true; + } + + const shouldExclude = exclude?.includes(name) ?? false; + return ( + (shouldInclude && !shouldExclude) || + // If the package name matches the root name, it's definitely part of the release group. + name === rootPackageName + ); +} + +/** + * Finds the name of the release group that a package belongs to. + * + * @param pkg - The package for which to fina a release group. + * @param definition - The "releaseGroups" config from the RepoLayout config/ + * @returns The name of the package's release group. + */ +export function findReleaseGroupForPackage( + pkg: IPackage | PackageName, + definition: Exclude, +): ReleaseGroupName | undefined { + for (const [rgName, def] of Object.entries(definition)) { + if (matchesReleaseGroupDefinition(pkg, def)) { + return rgName as ReleaseGroupName; + } + } +} + +const configName = "repoLayout"; + +/** + * A cosmiconfig explorer to find the repoLayout config. First looks for JavaScript config files and falls back to the + * `repoLayout` property in package.json. We create a single explorer here because cosmiconfig internally caches configs + * for performance. The cache is per-explorer, so re-using the same explorer is a minor perf improvement. + */ +const configExplorer = cosmiconfigSync(configName, { + searchPlaces: [ + `${configName}.config.cjs`, + `${configName}.config.js`, + + // Load from the fluidBuild config files as a fallback. + "fluidBuild.config.cjs", + "fluidBuild.config.js", + + // Or the repoLayout property in package.json + "package.json", + ], + packageProp: [configName], +}); + +/** + * Search a path for a repo layout config file, and return the parsed config and the path to the config file. + * + * @param searchPath - The path to start searching for config files in. + * @param noCache - If true, the config cache will be cleared and the config will be reloaded. + * @returns The loaded repoLayout config and the path to the config file. + * + * @throws If a config is not found or if the config version is not supported. + */ +export function getFluidRepoLayout( + searchPath: string, + noCache = false, +): { config: IFluidRepoLayout; configFilePath: string } { + if (noCache === true) { + configExplorer.clearCaches(); + } + + const configResult = configExplorer.search(searchPath); + if (configResult === null || configResult === undefined) { + throw new Error("No fluidRepo configuration found."); + } + const config = configResult.config as IFluidRepoLayout; + + // Only version 1 of the config is supported. If any other value is provided, throw an error. + if (config.version !== FLUIDREPO_CONFIG_VERSION) { + throw new Error( + `Configuration version is not supported: ${config?.version}. Config version must be ${FLUIDREPO_CONFIG_VERSION}.`, + ); + } + + return { config, configFilePath: configResult.filepath }; +} diff --git a/build-tools/packages/build-infrastructure/src/errors.ts b/build-tools/packages/build-infrastructure/src/errors.ts new file mode 100644 index 000000000000..fb4385bc02d8 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/errors.ts @@ -0,0 +1,13 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +/** + * An error thrown when a path is not within a Git repository. + */ +export class NotInGitRepository extends Error { + constructor(public readonly path: string) { + super(`Path is not in a Git repository: ${path}`); + } +} diff --git a/build-tools/packages/build-infrastructure/src/index.ts b/build-tools/packages/build-infrastructure/src/index.ts new file mode 100644 index 000000000000..8e5c39f02f29 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/index.ts @@ -0,0 +1,69 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +/** + * build-infrastructure package comment. + * + * @module default entrypoint + * @group API + * @category API + */ + +export { + type ReleaseGroupDefinition, + type WorkspaceDefinition, + type IFluidBuildDir, + type IFluidBuildDirs, + type IFluidBuildDirEntry, + type IFluidRepoLayout, + FLUIDREPO_CONFIG_VERSION, + getFluidRepoLayout, +} from "./config.js"; +export { NotInGitRepository } from "./errors.js"; +export type { + AdditionalPackageProps, + Installable, + IFluidRepo, + IPackage, + IReleaseGroup, + IWorkspace, + PackageJson, + PackageManagerName, + PackageName, + ReleaseGroupName, + Reloadable, + WorkspaceName, + FluidPackageJsonFields, + PackageDependency, + IPackageManager, +} from "./types.js"; +export { isIPackage, isIReleaseGroup } from "./types.js"; + +// export { +// filterPackages, +// type FilterablePackage, +// selectAndFilterPackages, +// type GlobString, +// AllPackagesSelectionCriteria, +// EmptySelectionCriteria, +// type PackageSelectionCriteria, +// type PackageFilterOptions, +// } from "./filter.js"; +// export { +// FluidRepo as FluidRepoBase, +// getAllDependenciesInRepo, +// loadFluidRepo, +// } from "./fluidRepo.js"; +// export { +// getFiles, +// findGitRootSync, +// getMergeBaseRemote, +// getRemote, +// getChangedSinceRef, +// } from "./git.js"; +// export { PackageBase } from "./package.js"; +// export { updatePackageJsonFile, updatePackageJsonFileAsync } from "./packageJsonUtils.js"; +// export { createPackageManager } from "./packageManagers.js"; +// export { setVersion } from "./versions.js"; diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/.changeset/README.md b/build-tools/packages/build-infrastructure/src/test/data/testRepo/.changeset/README.md new file mode 100644 index 000000000000..7de5f780575d --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/.changeset/README.md @@ -0,0 +1,11 @@ +# Changesets + +This folder contains changesets, which are markdown files that hold two key bits of information: + +1. a version type (following semver), and +2. change information to be added to a changelog. You can find the full documentation for it + [in the changesets section of our wiki](https://github.com/microsoft/FluidFramework/wiki/Changesets) or in [the official changesets documentation.](https://github.com/changesets/changesets) + +There is also a list of [frequently asked questions](https://github.com/microsoft/FluidFramework/wiki/Changesets-FAQ) in +the wiki. + diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/.changeset/bump-main-group-minor.md b/build-tools/packages/build-infrastructure/src/test/data/testRepo/.changeset/bump-main-group-minor.md new file mode 100644 index 000000000000..b71fbb4c343e --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/.changeset/bump-main-group-minor.md @@ -0,0 +1,5 @@ +--- +"pkg-a": minor +--- + +An example changeset. diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/.changeset/config.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/.changeset/config.json new file mode 100644 index 000000000000..9012ad8fd105 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/.changeset/config.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://unpkg.com/@changesets/config@2.3.0/schema.json", + "access": "public", + "baseBranch": "main", + "changelog": [ + "@fluid-private/changelog-generator-wrapper", + { + "repoBaseUrl": "https://github.com/microsoft/FluidFramework", + "issueTemplate": " ([#$issue]($repoBaseUrl/pull/$issue))", + "commitTemplate": " [$abbrevHash]($repoBaseUrl/commit/$hash)" + } + ], + "commit": false, + "fixed": [ + [ + "pkg-a", + "pkg-b", + "@private/pkg-c", + "@shared/shared" + ], + [ + "@group2/pkg-d", + "@group2/pkg-e" + ], + [ + "@group3/pkg-f", + "@group3/pkg-g" + ] + ], + "ignore": [], + "linked": [], + "updateInternalDependencies": "minor", + "bumpVersionsWithWorkspaceProtocolOnly": true +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/fluidBuild.config.cjs b/build-tools/packages/build-infrastructure/src/test/data/testRepo/fluidBuild.config.cjs new file mode 100644 index 000000000000..3ae27cf80d09 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/fluidBuild.config.cjs @@ -0,0 +1,61 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +// Enable TypeScript type-checking for this file. +// See https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#ts-check +// @ts-check + +/** + * @type {import("@fluid-tools/build-infrastructure").IFluidRepoLayout & import("@fluid-tools/build-cli").FlubConfig} + */ +const config = { + version: 1, + repoLayout: { + workspaces: { + main: { + directory: ".", + releaseGroups: { + main: { + include: ["pkg-a", "pkg-b", "@shared", "@private"], + rootPackageName: "main-release-group-root", + }, + group2: { + include: ["@group2"], + }, + group3: { + include: ["@group3"], + }, + }, + }, + second: { + directory: "./second", + releaseGroups: { + "second-release-group": { + include: ["*"], + rootPackageName: "second-release-group-root", + }, + }, + }, + }, + }, + + // The configuration used by the `flub generate changeset-config` command. + changesetConfig: { + changelog: [ + "@fluid-private/changelog-generator-wrapper", + { + repoBaseUrl: "https://github.com/microsoft/FluidFramework", + issueTemplate: " ([#$issue]($repoBaseUrl/pull/$issue))", + commitTemplate: " [$abbrevHash]($repoBaseUrl/commit/$hash)", + }, + ], + commit: false, + access: "public", + baseBranch: "main", + updateInternalDependencies: "patch", + }, +}; + +module.exports = config; diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/package.json new file mode 100644 index 000000000000..6208179e8a51 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/package.json @@ -0,0 +1,20 @@ +{ + "name": "main-release-group-root", + "version": "1.0.0", + "description": "Test package", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure/src/test/data/testRepo" + }, + "license": "MIT", + "author": "Microsoft and contributors", + "dependencies": { + "@fluid-private/changelog-generator-wrapper": "link:../../../../../../../packages/tools/changelog-generator-wrapper", + "@fluid-tools/build-infrastructure": "link:../../../../../build-infrastructure" + }, + "devDependencies": { + "@changesets/cli": "^2.27.9" + } +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group2/pkg-d/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group2/pkg-d/package.json new file mode 100644 index 000000000000..83999191f9cf --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group2/pkg-d/package.json @@ -0,0 +1,16 @@ +{ + "name": "@group2/pkg-d", + "version": "1.0.0", + "description": "Test package", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group2/pkg-d" + }, + "license": "MIT", + "author": "Microsoft and contributors", + "dependencies": { + "@group2/pkg-e": "workspace:~" + } +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group2/pkg-e/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group2/pkg-e/package.json new file mode 100644 index 000000000000..2142f92283b4 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group2/pkg-e/package.json @@ -0,0 +1,14 @@ +{ + "name": "@group2/pkg-e", + "version": "1.0.0", + "description": "Test package", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group2/pkg-e" + }, + "license": "MIT", + "author": "Microsoft and contributors", + "dependencies": {} +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-f/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-f/package.json new file mode 100644 index 000000000000..2b2bffa838e6 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-f/package.json @@ -0,0 +1,17 @@ +{ + "name": "@group3/pkg-f", + "version": "1.0.0", + "description": "Test package", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-f" + }, + "license": "MIT", + "author": "Microsoft and contributors", + "dependencies": { + "@group2/pkg-e": "workspace:~", + "@group3/pkg-g": "workspace:~" + } +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-f/src/index.mjs b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-f/src/index.mjs new file mode 100644 index 000000000000..bf55e2ddd240 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-f/src/index.mjs @@ -0,0 +1 @@ +export const FOO = 1; diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-g/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-g/package.json new file mode 100644 index 000000000000..dbc99a71e290 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-g/package.json @@ -0,0 +1,13 @@ +{ + "name": "@group3/pkg-g", + "version": "1.0.0", + "description": "Test package", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/group3/pkg-g" + }, + "license": "MIT", + "author": "Microsoft and contributors" +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-a/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-a/package.json new file mode 100644 index 000000000000..7d6104adc4c0 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-a/package.json @@ -0,0 +1,17 @@ +{ + "name": "pkg-a", + "version": "1.0.0", + "description": "Test package", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-a" + }, + "license": "MIT", + "author": "Microsoft and contributors", + "dependencies": { + "@shared/shared": "workspace:~", + "pkg-b": "workspace:~" + } +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-b/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-b/package.json new file mode 100644 index 000000000000..b4977d923789 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-b/package.json @@ -0,0 +1,16 @@ +{ + "name": "pkg-b", + "version": "1.0.0", + "description": "Test package", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-b" + }, + "license": "MIT", + "author": "Microsoft and contributors", + "dependencies": { + "pkg-b": "workspace:~" + } +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-c/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-c/package.json new file mode 100644 index 000000000000..1904ea768980 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-c/package.json @@ -0,0 +1,17 @@ +{ + "name": "@private/pkg-c", + "version": "1.0.0", + "private": true, + "description": "Test package", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/pkg-c" + }, + "license": "MIT", + "author": "Microsoft and contributors", + "dependencies": { + "pkg-b": "workspace:~" + } +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/shared/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/shared/package.json new file mode 100644 index 000000000000..f154760b901f --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/shared/package.json @@ -0,0 +1,17 @@ +{ + "name": "@shared/shared", + "version": "1.0.0", + "description": "Test package", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/shared" + }, + "license": "MIT", + "author": "Microsoft and contributors", + "dependencies": { + "@group2/pkg-d": "1.0.0", + "@group3/pkg-g": "1.0.0" + } +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/pnpm-lock.yaml b/build-tools/packages/build-infrastructure/src/test/data/testRepo/pnpm-lock.yaml new file mode 100644 index 000000000000..08d35f432ff5 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/pnpm-lock.yaml @@ -0,0 +1,766 @@ +lockfileVersion: '6.0' + +settings: + autoInstallPeers: true + excludeLinksFromLockfile: false + +importers: + + .: + dependencies: + '@fluid-private/changelog-generator-wrapper': + specifier: link:../../../../../../../packages/tools/changelog-generator-wrapper + version: link:../../../../../../../packages/tools/changelog-generator-wrapper + '@fluid-tools/build-infrastructure': + specifier: link:../../../../../build-infrastructure + version: link:../../../.. + devDependencies: + '@changesets/cli': + specifier: ^2.27.9 + version: 2.27.9 + + packages/group2/pkg-d: + dependencies: + '@group2/pkg-e': + specifier: workspace:~ + version: link:../pkg-e + + packages/group2/pkg-e: {} + + packages/group3/pkg-f: + dependencies: + '@group2/pkg-e': + specifier: workspace:~ + version: link:../../group2/pkg-e + '@group3/pkg-g': + specifier: workspace:~ + version: link:../pkg-g + + packages/group3/pkg-g: {} + + packages/pkg-a: + dependencies: + '@shared/shared': + specifier: workspace:~ + version: link:../shared + pkg-b: + specifier: workspace:~ + version: link:../pkg-b + + packages/pkg-b: + dependencies: + pkg-b: + specifier: workspace:~ + version: 'link:' + + packages/pkg-c: + dependencies: + pkg-b: + specifier: workspace:~ + version: link:../pkg-b + + packages/shared: + dependencies: + '@group2/pkg-d': + specifier: 1.0.0 + version: link:../group2/pkg-d + '@group3/pkg-g': + specifier: 1.0.0 + version: link:../group3/pkg-g + +packages: + + /@babel/runtime@7.25.7: + resolution: {integrity: sha512-FjoyLe754PMiYsFaN5C94ttGiOmBNYTf6pLr4xXHAT5uctHb092PBszndLDR5XA/jghQvn4n7JMHl7dmTgbm9w==} + engines: {node: '>=6.9.0'} + dependencies: + regenerator-runtime: 0.14.1 + dev: true + + /@changesets/apply-release-plan@7.0.5: + resolution: {integrity: sha512-1cWCk+ZshEkSVEZrm2fSj1Gz8sYvxgUL4Q78+1ZZqeqfuevPTPk033/yUZ3df8BKMohkqqHfzj0HOOrG0KtXTw==} + dependencies: + '@changesets/config': 3.0.3 + '@changesets/get-version-range-type': 0.4.0 + '@changesets/git': 3.0.1 + '@changesets/should-skip-package': 0.1.1 + '@changesets/types': 6.0.0 + '@manypkg/get-packages': 1.1.3 + detect-indent: 6.1.0 + fs-extra: 7.0.1 + lodash.startcase: 4.4.0 + outdent: 0.5.0 + prettier: 2.8.8 + resolve-from: 5.0.0 + semver: 7.6.3 + dev: true + + /@changesets/assemble-release-plan@6.0.4: + resolution: {integrity: sha512-nqICnvmrwWj4w2x0fOhVj2QEGdlUuwVAwESrUo5HLzWMI1rE5SWfsr9ln+rDqWB6RQ2ZyaMZHUcU7/IRaUJS+Q==} + dependencies: + '@changesets/errors': 0.2.0 + '@changesets/get-dependents-graph': 2.1.2 + '@changesets/should-skip-package': 0.1.1 + '@changesets/types': 6.0.0 + '@manypkg/get-packages': 1.1.3 + semver: 7.6.3 + dev: true + + /@changesets/changelog-git@0.2.0: + resolution: {integrity: sha512-bHOx97iFI4OClIT35Lok3sJAwM31VbUM++gnMBV16fdbtBhgYu4dxsphBF/0AZZsyAHMrnM0yFcj5gZM1py6uQ==} + dependencies: + '@changesets/types': 6.0.0 + dev: true + + /@changesets/cli@2.27.9: + resolution: {integrity: sha512-q42a/ZbDnxPpCb5Wkm6tMVIxgeI9C/bexntzTeCFBrQEdpisQqk8kCHllYZMDjYtEc1ZzumbMJAG8H0Z4rdvjg==} + hasBin: true + dependencies: + '@changesets/apply-release-plan': 7.0.5 + '@changesets/assemble-release-plan': 6.0.4 + '@changesets/changelog-git': 0.2.0 + '@changesets/config': 3.0.3 + '@changesets/errors': 0.2.0 + '@changesets/get-dependents-graph': 2.1.2 + '@changesets/get-release-plan': 4.0.4 + '@changesets/git': 3.0.1 + '@changesets/logger': 0.1.1 + '@changesets/pre': 2.0.1 + '@changesets/read': 0.6.1 + '@changesets/should-skip-package': 0.1.1 + '@changesets/types': 6.0.0 + '@changesets/write': 0.3.2 + '@manypkg/get-packages': 1.1.3 + ansi-colors: 4.1.3 + ci-info: 3.9.0 + enquirer: 2.4.1 + external-editor: 3.1.0 + fs-extra: 7.0.1 + mri: 1.2.0 + p-limit: 2.3.0 + package-manager-detector: 0.2.1 + picocolors: 1.1.0 + resolve-from: 5.0.0 + semver: 7.6.3 + spawndamnit: 2.0.0 + term-size: 2.2.1 + dev: true + + /@changesets/config@3.0.3: + resolution: {integrity: sha512-vqgQZMyIcuIpw9nqFIpTSNyc/wgm/Lu1zKN5vECy74u95Qx/Wa9g27HdgO4NkVAaq+BGA8wUc/qvbvVNs93n6A==} + dependencies: + '@changesets/errors': 0.2.0 + '@changesets/get-dependents-graph': 2.1.2 + '@changesets/logger': 0.1.1 + '@changesets/types': 6.0.0 + '@manypkg/get-packages': 1.1.3 + fs-extra: 7.0.1 + micromatch: 4.0.8 + dev: true + + /@changesets/errors@0.2.0: + resolution: {integrity: sha512-6BLOQUscTpZeGljvyQXlWOItQyU71kCdGz7Pi8H8zdw6BI0g3m43iL4xKUVPWtG+qrrL9DTjpdn8eYuCQSRpow==} + dependencies: + extendable-error: 0.1.7 + dev: true + + /@changesets/get-dependents-graph@2.1.2: + resolution: {integrity: sha512-sgcHRkiBY9i4zWYBwlVyAjEM9sAzs4wYVwJUdnbDLnVG3QwAaia1Mk5P8M7kraTOZN+vBET7n8KyB0YXCbFRLQ==} + dependencies: + '@changesets/types': 6.0.0 + '@manypkg/get-packages': 1.1.3 + picocolors: 1.1.0 + semver: 7.6.3 + dev: true + + /@changesets/get-release-plan@4.0.4: + resolution: {integrity: sha512-SicG/S67JmPTrdcc9Vpu0wSQt7IiuN0dc8iR5VScnnTVPfIaLvKmEGRvIaF0kcn8u5ZqLbormZNTO77bCEvyWw==} + dependencies: + '@changesets/assemble-release-plan': 6.0.4 + '@changesets/config': 3.0.3 + '@changesets/pre': 2.0.1 + '@changesets/read': 0.6.1 + '@changesets/types': 6.0.0 + '@manypkg/get-packages': 1.1.3 + dev: true + + /@changesets/get-version-range-type@0.4.0: + resolution: {integrity: sha512-hwawtob9DryoGTpixy1D3ZXbGgJu1Rhr+ySH2PvTLHvkZuQ7sRT4oQwMh0hbqZH1weAooedEjRsbrWcGLCeyVQ==} + dev: true + + /@changesets/git@3.0.1: + resolution: {integrity: sha512-pdgHcYBLCPcLd82aRcuO0kxCDbw/yISlOtkmwmE8Odo1L6hSiZrBOsRl84eYG7DRCab/iHnOkWqExqc4wxk2LQ==} + dependencies: + '@changesets/errors': 0.2.0 + '@manypkg/get-packages': 1.1.3 + is-subdir: 1.2.0 + micromatch: 4.0.8 + spawndamnit: 2.0.0 + dev: true + + /@changesets/logger@0.1.1: + resolution: {integrity: sha512-OQtR36ZlnuTxKqoW4Sv6x5YIhOmClRd5pWsjZsddYxpWs517R0HkyiefQPIytCVh4ZcC5x9XaG8KTdd5iRQUfg==} + dependencies: + picocolors: 1.1.0 + dev: true + + /@changesets/parse@0.4.0: + resolution: {integrity: sha512-TS/9KG2CdGXS27S+QxbZXgr8uPsP4yNJYb4BC2/NeFUj80Rni3TeD2qwWmabymxmrLo7JEsytXH1FbpKTbvivw==} + dependencies: + '@changesets/types': 6.0.0 + js-yaml: 3.14.1 + dev: true + + /@changesets/pre@2.0.1: + resolution: {integrity: sha512-vvBJ/If4jKM4tPz9JdY2kGOgWmCowUYOi5Ycv8dyLnEE8FgpYYUo1mgJZxcdtGGP3aG8rAQulGLyyXGSLkIMTQ==} + dependencies: + '@changesets/errors': 0.2.0 + '@changesets/types': 6.0.0 + '@manypkg/get-packages': 1.1.3 + fs-extra: 7.0.1 + dev: true + + /@changesets/read@0.6.1: + resolution: {integrity: sha512-jYMbyXQk3nwP25nRzQQGa1nKLY0KfoOV7VLgwucI0bUO8t8ZLCr6LZmgjXsiKuRDc+5A6doKPr9w2d+FEJ55zQ==} + dependencies: + '@changesets/git': 3.0.1 + '@changesets/logger': 0.1.1 + '@changesets/parse': 0.4.0 + '@changesets/types': 6.0.0 + fs-extra: 7.0.1 + p-filter: 2.1.0 + picocolors: 1.1.0 + dev: true + + /@changesets/should-skip-package@0.1.1: + resolution: {integrity: sha512-H9LjLbF6mMHLtJIc/eHR9Na+MifJ3VxtgP/Y+XLn4BF7tDTEN1HNYtH6QMcjP1uxp9sjaFYmW8xqloaCi/ckTg==} + dependencies: + '@changesets/types': 6.0.0 + '@manypkg/get-packages': 1.1.3 + dev: true + + /@changesets/types@4.1.0: + resolution: {integrity: sha512-LDQvVDv5Kb50ny2s25Fhm3d9QSZimsoUGBsUioj6MC3qbMUCuC8GPIvk/M6IvXx3lYhAs0lwWUQLb+VIEUCECw==} + dev: true + + /@changesets/types@6.0.0: + resolution: {integrity: sha512-b1UkfNulgKoWfqyHtzKS5fOZYSJO+77adgL7DLRDr+/7jhChN+QcHnbjiQVOz/U+Ts3PGNySq7diAItzDgugfQ==} + dev: true + + /@changesets/write@0.3.2: + resolution: {integrity: sha512-kDxDrPNpUgsjDbWBvUo27PzKX4gqeKOlhibaOXDJA6kuBisGqNHv/HwGJrAu8U/dSf8ZEFIeHIPtvSlZI1kULw==} + dependencies: + '@changesets/types': 6.0.0 + fs-extra: 7.0.1 + human-id: 1.0.2 + prettier: 2.8.8 + dev: true + + /@manypkg/find-root@1.1.0: + resolution: {integrity: sha512-mki5uBvhHzO8kYYix/WRy2WX8S3B5wdVSc9D6KcU5lQNglP2yt58/VfLuAK49glRXChosY8ap2oJ1qgma3GUVA==} + dependencies: + '@babel/runtime': 7.25.7 + '@types/node': 12.20.55 + find-up: 4.1.0 + fs-extra: 8.1.0 + dev: true + + /@manypkg/get-packages@1.1.3: + resolution: {integrity: sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A==} + dependencies: + '@babel/runtime': 7.25.7 + '@changesets/types': 4.1.0 + '@manypkg/find-root': 1.1.0 + fs-extra: 8.1.0 + globby: 11.1.0 + read-yaml-file: 1.1.0 + dev: true + + /@nodelib/fs.scandir@2.1.5: + resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==} + engines: {node: '>= 8'} + dependencies: + '@nodelib/fs.stat': 2.0.5 + run-parallel: 1.2.0 + dev: true + + /@nodelib/fs.stat@2.0.5: + resolution: {integrity: sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==} + engines: {node: '>= 8'} + dev: true + + /@nodelib/fs.walk@1.2.8: + resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==} + engines: {node: '>= 8'} + dependencies: + '@nodelib/fs.scandir': 2.1.5 + fastq: 1.17.1 + dev: true + + /@types/node@12.20.55: + resolution: {integrity: sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==} + dev: true + + /ansi-colors@4.1.3: + resolution: {integrity: sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==} + engines: {node: '>=6'} + dev: true + + /ansi-regex@5.0.1: + resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==} + engines: {node: '>=8'} + dev: true + + /argparse@1.0.10: + resolution: {integrity: sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==} + dependencies: + sprintf-js: 1.0.3 + dev: true + + /array-union@2.1.0: + resolution: {integrity: sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==} + engines: {node: '>=8'} + dev: true + + /better-path-resolve@1.0.0: + resolution: {integrity: sha512-pbnl5XzGBdrFU/wT4jqmJVPn2B6UHPBOhzMQkY/SPUPB6QtUXtmBHBIwCbXJol93mOpGMnQyP/+BB19q04xj7g==} + engines: {node: '>=4'} + dependencies: + is-windows: 1.0.2 + dev: true + + /braces@3.0.3: + resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==} + engines: {node: '>=8'} + dependencies: + fill-range: 7.1.1 + dev: true + + /chardet@0.7.0: + resolution: {integrity: sha512-mT8iDcrh03qDGRRmoA2hmBJnxpllMR+0/0qlzjqZES6NdiWDcZkCNAk4rPFZ9Q85r27unkiNNg8ZOiwZXBHwcA==} + dev: true + + /ci-info@3.9.0: + resolution: {integrity: sha512-NIxF55hv4nSqQswkAeiOi1r83xy8JldOFDTWiug55KBu9Jnblncd2U6ViHmYgHf01TPZS77NJBhBMKdWj9HQMQ==} + engines: {node: '>=8'} + dev: true + + /cross-spawn@5.1.0: + resolution: {integrity: sha512-pTgQJ5KC0d2hcY8eyL1IzlBPYjTkyH72XRZPnLyKus2mBfNjQs3klqbJU2VILqZryAZUt9JOb3h/mWMy23/f5A==} + dependencies: + lru-cache: 4.1.5 + shebang-command: 1.2.0 + which: 1.3.1 + dev: true + + /detect-indent@6.1.0: + resolution: {integrity: sha512-reYkTUJAZb9gUuZ2RvVCNhVHdg62RHnJ7WJl8ftMi4diZ6NWlciOzQN88pUhSELEwflJht4oQDv0F0BMlwaYtA==} + engines: {node: '>=8'} + dev: true + + /dir-glob@3.0.1: + resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==} + engines: {node: '>=8'} + dependencies: + path-type: 4.0.0 + dev: true + + /enquirer@2.4.1: + resolution: {integrity: sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ==} + engines: {node: '>=8.6'} + dependencies: + ansi-colors: 4.1.3 + strip-ansi: 6.0.1 + dev: true + + /esprima@4.0.1: + resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==} + engines: {node: '>=4'} + hasBin: true + dev: true + + /extendable-error@0.1.7: + resolution: {integrity: sha512-UOiS2in6/Q0FK0R0q6UY9vYpQ21mr/Qn1KOnte7vsACuNJf514WvCCUHSRCPcgjPT2bAhNIJdlE6bVap1GKmeg==} + dev: true + + /external-editor@3.1.0: + resolution: {integrity: sha512-hMQ4CX1p1izmuLYyZqLMO/qGNw10wSv9QDCPfzXfyFrOaCSSoRfqE1Kf1s5an66J5JZC62NewG+mK49jOCtQew==} + engines: {node: '>=4'} + dependencies: + chardet: 0.7.0 + iconv-lite: 0.4.24 + tmp: 0.0.33 + dev: true + + /fast-glob@3.3.2: + resolution: {integrity: sha512-oX2ruAFQwf/Orj8m737Y5adxDQO0LAB7/S5MnxCdTNDd4p6BsyIVsv9JQsATbTSq8KHRpLwIHbVlUNatxd+1Ow==} + engines: {node: '>=8.6.0'} + dependencies: + '@nodelib/fs.stat': 2.0.5 + '@nodelib/fs.walk': 1.2.8 + glob-parent: 5.1.2 + merge2: 1.4.1 + micromatch: 4.0.8 + dev: true + + /fastq@1.17.1: + resolution: {integrity: sha512-sRVD3lWVIXWg6By68ZN7vho9a1pQcN/WBFaAAsDDFzlJjvoGx0P8z7V1t72grFJfJhu3YPZBuu25f7Kaw2jN1w==} + dependencies: + reusify: 1.0.4 + dev: true + + /fill-range@7.1.1: + resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==} + engines: {node: '>=8'} + dependencies: + to-regex-range: 5.0.1 + dev: true + + /find-up@4.1.0: + resolution: {integrity: sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==} + engines: {node: '>=8'} + dependencies: + locate-path: 5.0.0 + path-exists: 4.0.0 + dev: true + + /fs-extra@7.0.1: + resolution: {integrity: sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==} + engines: {node: '>=6 <7 || >=8'} + dependencies: + graceful-fs: 4.2.11 + jsonfile: 4.0.0 + universalify: 0.1.2 + dev: true + + /fs-extra@8.1.0: + resolution: {integrity: sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==} + engines: {node: '>=6 <7 || >=8'} + dependencies: + graceful-fs: 4.2.11 + jsonfile: 4.0.0 + universalify: 0.1.2 + dev: true + + /glob-parent@5.1.2: + resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==} + engines: {node: '>= 6'} + dependencies: + is-glob: 4.0.3 + dev: true + + /globby@11.1.0: + resolution: {integrity: sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==} + engines: {node: '>=10'} + dependencies: + array-union: 2.1.0 + dir-glob: 3.0.1 + fast-glob: 3.3.2 + ignore: 5.3.2 + merge2: 1.4.1 + slash: 3.0.0 + dev: true + + /graceful-fs@4.2.11: + resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==} + dev: true + + /human-id@1.0.2: + resolution: {integrity: sha512-UNopramDEhHJD+VR+ehk8rOslwSfByxPIZyJRfV739NDhN5LF1fa1MqnzKm2lGTQRjNrjK19Q5fhkgIfjlVUKw==} + dev: true + + /iconv-lite@0.4.24: + resolution: {integrity: sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==} + engines: {node: '>=0.10.0'} + dependencies: + safer-buffer: 2.1.2 + dev: true + + /ignore@5.3.2: + resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==} + engines: {node: '>= 4'} + dev: true + + /is-extglob@2.1.1: + resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==} + engines: {node: '>=0.10.0'} + dev: true + + /is-glob@4.0.3: + resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==} + engines: {node: '>=0.10.0'} + dependencies: + is-extglob: 2.1.1 + dev: true + + /is-number@7.0.0: + resolution: {integrity: sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==} + engines: {node: '>=0.12.0'} + dev: true + + /is-subdir@1.2.0: + resolution: {integrity: sha512-2AT6j+gXe/1ueqbW6fLZJiIw3F8iXGJtt0yDrZaBhAZEG1raiTxKWU+IPqMCzQAXOUCKdA4UDMgacKH25XG2Cw==} + engines: {node: '>=4'} + dependencies: + better-path-resolve: 1.0.0 + dev: true + + /is-windows@1.0.2: + resolution: {integrity: sha512-eXK1UInq2bPmjyX6e3VHIzMLobc4J94i4AWn+Hpq3OU5KkrRC96OAcR3PRJ/pGu6m8TRnBHP9dkXQVsT/COVIA==} + engines: {node: '>=0.10.0'} + dev: true + + /isexe@2.0.0: + resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==} + dev: true + + /js-yaml@3.14.1: + resolution: {integrity: sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==} + hasBin: true + dependencies: + argparse: 1.0.10 + esprima: 4.0.1 + dev: true + + /jsonfile@4.0.0: + resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==} + optionalDependencies: + graceful-fs: 4.2.11 + dev: true + + /locate-path@5.0.0: + resolution: {integrity: sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==} + engines: {node: '>=8'} + dependencies: + p-locate: 4.1.0 + dev: true + + /lodash.startcase@4.4.0: + resolution: {integrity: sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg==} + dev: true + + /lru-cache@4.1.5: + resolution: {integrity: sha512-sWZlbEP2OsHNkXrMl5GYk/jKk70MBng6UU4YI/qGDYbgf6YbP4EvmqISbXCoJiRKs+1bSpFHVgQxvJ17F2li5g==} + dependencies: + pseudomap: 1.0.2 + yallist: 2.1.2 + dev: true + + /merge2@1.4.1: + resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==} + engines: {node: '>= 8'} + dev: true + + /micromatch@4.0.8: + resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==} + engines: {node: '>=8.6'} + dependencies: + braces: 3.0.3 + picomatch: 2.3.1 + dev: true + + /mri@1.2.0: + resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==} + engines: {node: '>=4'} + dev: true + + /os-tmpdir@1.0.2: + resolution: {integrity: sha512-D2FR03Vir7FIu45XBY20mTb+/ZSWB00sjU9jdQXt83gDrI4Ztz5Fs7/yy74g2N5SVQY4xY1qDr4rNddwYRVX0g==} + engines: {node: '>=0.10.0'} + dev: true + + /outdent@0.5.0: + resolution: {integrity: sha512-/jHxFIzoMXdqPzTaCpFzAAWhpkSjZPF4Vsn6jAfNpmbH/ymsmd7Qc6VE9BGn0L6YMj6uwpQLxCECpus4ukKS9Q==} + dev: true + + /p-filter@2.1.0: + resolution: {integrity: sha512-ZBxxZ5sL2HghephhpGAQdoskxplTwr7ICaehZwLIlfL6acuVgZPm8yBNuRAFBGEqtD/hmUeq9eqLg2ys9Xr/yw==} + engines: {node: '>=8'} + dependencies: + p-map: 2.1.0 + dev: true + + /p-limit@2.3.0: + resolution: {integrity: sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==} + engines: {node: '>=6'} + dependencies: + p-try: 2.2.0 + dev: true + + /p-locate@4.1.0: + resolution: {integrity: sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==} + engines: {node: '>=8'} + dependencies: + p-limit: 2.3.0 + dev: true + + /p-map@2.1.0: + resolution: {integrity: sha512-y3b8Kpd8OAN444hxfBbFfj1FY/RjtTd8tzYwhUqNYXx0fXx2iX4maP4Qr6qhIKbQXI02wTLAda4fYUbDagTUFw==} + engines: {node: '>=6'} + dev: true + + /p-try@2.2.0: + resolution: {integrity: sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==} + engines: {node: '>=6'} + dev: true + + /package-manager-detector@0.2.1: + resolution: {integrity: sha512-/hVW2fZvAdEas+wyKh0SnlZ2mx0NIa1+j11YaQkogEJkcMErbwchHCuo8z7lEtajZJQZ6rgZNVTWMVVd71Bjng==} + dev: true + + /path-exists@4.0.0: + resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==} + engines: {node: '>=8'} + dev: true + + /path-type@4.0.0: + resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==} + engines: {node: '>=8'} + dev: true + + /picocolors@1.1.0: + resolution: {integrity: sha512-TQ92mBOW0l3LeMeyLV6mzy/kWr8lkd/hp3mTg7wYK7zJhuBStmGMBG0BdeDZS/dZx1IukaX6Bk11zcln25o1Aw==} + dev: true + + /picomatch@2.3.1: + resolution: {integrity: sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==} + engines: {node: '>=8.6'} + dev: true + + /pify@4.0.1: + resolution: {integrity: sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g==} + engines: {node: '>=6'} + dev: true + + /prettier@2.8.8: + resolution: {integrity: sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==} + engines: {node: '>=10.13.0'} + hasBin: true + dev: true + + /pseudomap@1.0.2: + resolution: {integrity: sha512-b/YwNhb8lk1Zz2+bXXpS/LK9OisiZZ1SNsSLxN1x2OXVEhW2Ckr/7mWE5vrC1ZTiJlD9g19jWszTmJsB+oEpFQ==} + dev: true + + /queue-microtask@1.2.3: + resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==} + dev: true + + /read-yaml-file@1.1.0: + resolution: {integrity: sha512-VIMnQi/Z4HT2Fxuwg5KrY174U1VdUIASQVWXXyqtNRtxSr9IYkn1rsI6Tb6HsrHCmB7gVpNwX6JxPTHcH6IoTA==} + engines: {node: '>=6'} + dependencies: + graceful-fs: 4.2.11 + js-yaml: 3.14.1 + pify: 4.0.1 + strip-bom: 3.0.0 + dev: true + + /regenerator-runtime@0.14.1: + resolution: {integrity: sha512-dYnhHh0nJoMfnkZs6GmmhFknAGRrLznOu5nc9ML+EJxGvrx6H7teuevqVqCuPcPK//3eDrrjQhehXVx9cnkGdw==} + dev: true + + /resolve-from@5.0.0: + resolution: {integrity: sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==} + engines: {node: '>=8'} + dev: true + + /reusify@1.0.4: + resolution: {integrity: sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==} + engines: {iojs: '>=1.0.0', node: '>=0.10.0'} + dev: true + + /run-parallel@1.2.0: + resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==} + dependencies: + queue-microtask: 1.2.3 + dev: true + + /safer-buffer@2.1.2: + resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==} + dev: true + + /semver@7.6.3: + resolution: {integrity: sha512-oVekP1cKtI+CTDvHWYFUcMtsK/00wmAEfyqKfNdARm8u1wNVhSgaX7A8d4UuIlUI5e84iEwOhs7ZPYRmzU9U6A==} + engines: {node: '>=10'} + hasBin: true + dev: true + + /shebang-command@1.2.0: + resolution: {integrity: sha512-EV3L1+UQWGor21OmnvojK36mhg+TyIKDh3iFBKBohr5xeXIhNBcx8oWdgkTEEQ+BEFFYdLRuqMfd5L84N1V5Vg==} + engines: {node: '>=0.10.0'} + dependencies: + shebang-regex: 1.0.0 + dev: true + + /shebang-regex@1.0.0: + resolution: {integrity: sha512-wpoSFAxys6b2a2wHZ1XpDSgD7N9iVjg29Ph9uV/uaP9Ex/KXlkTZTeddxDPSYQpgvzKLGJke2UU0AzoGCjNIvQ==} + engines: {node: '>=0.10.0'} + dev: true + + /signal-exit@3.0.7: + resolution: {integrity: sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==} + dev: true + + /slash@3.0.0: + resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==} + engines: {node: '>=8'} + dev: true + + /spawndamnit@2.0.0: + resolution: {integrity: sha512-j4JKEcncSjFlqIwU5L/rp2N5SIPsdxaRsIv678+TZxZ0SRDJTm8JrxJMjE/XuiEZNEir3S8l0Fa3Ke339WI4qA==} + dependencies: + cross-spawn: 5.1.0 + signal-exit: 3.0.7 + dev: true + + /sprintf-js@1.0.3: + resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==} + dev: true + + /strip-ansi@6.0.1: + resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==} + engines: {node: '>=8'} + dependencies: + ansi-regex: 5.0.1 + dev: true + + /strip-bom@3.0.0: + resolution: {integrity: sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==} + engines: {node: '>=4'} + dev: true + + /term-size@2.2.1: + resolution: {integrity: sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg==} + engines: {node: '>=8'} + dev: true + + /tmp@0.0.33: + resolution: {integrity: sha512-jRCJlojKnZ3addtTOjdIqoRuPEKBvNXcGYqzO6zWZX8KfKEpnGY5jfggJQ3EjKuu8D4bJRr0y+cYJFmYbImXGw==} + engines: {node: '>=0.6.0'} + dependencies: + os-tmpdir: 1.0.2 + dev: true + + /to-regex-range@5.0.1: + resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==} + engines: {node: '>=8.0'} + dependencies: + is-number: 7.0.0 + dev: true + + /universalify@0.1.2: + resolution: {integrity: sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==} + engines: {node: '>= 4.0.0'} + dev: true + + /which@1.3.1: + resolution: {integrity: sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==} + hasBin: true + dependencies: + isexe: 2.0.0 + dev: true + + /yallist@2.1.2: + resolution: {integrity: sha512-ncTzHV7NvsQZkYe1DW7cbDLm0YpzHmZF5r/iyP3ZnQtMiJ+pjzisCiMNI+Sj+xQF5pXhSHxSB3uDbsBTzY/c2A==} + dev: true diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/pnpm-workspace.yaml b/build-tools/packages/build-infrastructure/src/test/data/testRepo/pnpm-workspace.yaml new file mode 100644 index 000000000000..9c9be4ba8d5e --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/pnpm-workspace.yaml @@ -0,0 +1,2 @@ +packages: + - "packages/**" diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/package.json new file mode 100644 index 000000000000..bc836afc9b8f --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/package.json @@ -0,0 +1,16 @@ +{ + "name": "second-release-group-root", + "version": "2.0.0", + "description": "Test package", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure/src/test/data/testRepo/second" + }, + "license": "MIT", + "author": "Microsoft and contributors", + "dependencies": { + "@fluid-tools/build-infrastructure": "link:../../../../../../build-infrastructure" + } +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/packages/other-pkg-a/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/packages/other-pkg-a/package.json new file mode 100644 index 000000000000..098dfddf8bb2 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/packages/other-pkg-a/package.json @@ -0,0 +1,16 @@ +{ + "name": "other-pkg-a", + "version": "2.0.0", + "description": "Test package", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure/src/test/data/testRepo/second/packages/other-pkg-a" + }, + "license": "MIT", + "author": "Microsoft and contributors", + "dependencies": { + "other-pkg-b": "workspace:~" + } +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/packages/other-pkg-b/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/packages/other-pkg-b/package.json new file mode 100644 index 000000000000..34d919d483b3 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/packages/other-pkg-b/package.json @@ -0,0 +1,13 @@ +{ + "name": "other-pkg-b", + "version": "2.0.0", + "description": "Test package", + "homepage": "https://fluidframework.com", + "repository": { + "type": "git", + "url": "https://github.com/microsoft/FluidFramework.git", + "directory": "build-tools/packages/build-infrastructure/src/test/data/testRepo/second/packages/other-pkg-b" + }, + "license": "MIT", + "author": "Microsoft and contributors" +} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/pnpm-lock.yaml b/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/pnpm-lock.yaml new file mode 100644 index 000000000000..ba83dc5e001d --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/pnpm-lock.yaml @@ -0,0 +1,21 @@ +lockfileVersion: '6.0' + +settings: + autoInstallPeers: true + excludeLinksFromLockfile: false + +importers: + + .: + dependencies: + '@fluid-tools/build-infrastructure': + specifier: link:../../../../../../build-infrastructure + version: link:../../../../.. + + packages/other-pkg-a: + dependencies: + other-pkg-b: + specifier: workspace:~ + version: link:../other-pkg-b + + packages/other-pkg-b: {} diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/pnpm-workspace.yaml b/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/pnpm-workspace.yaml new file mode 100644 index 000000000000..dee51e928d8a --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/second/pnpm-workspace.yaml @@ -0,0 +1,2 @@ +packages: + - "packages/*" diff --git a/build-tools/packages/build-infrastructure/src/test/dirname.cts b/build-tools/packages/build-infrastructure/src/test/dirname.cts new file mode 100644 index 000000000000..e9ce6931d4db --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/dirname.cts @@ -0,0 +1,14 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +// Problem: +// - `__dirname` is not defined in ESM +// - `import.meta.url` is not defined in CJS +// Solution: +// - Export '__dirname' from a .cjs file in the same directory. +// +// Note that *.cjs files are always CommonJS, but can be imported from ESM. +// eslint-disable-next-line unicorn/prefer-module -- this is used for ESM/CJS interop +export const _dirname = __dirname; diff --git a/build-tools/packages/build-infrastructure/src/test/init.ts b/build-tools/packages/build-infrastructure/src/test/init.ts new file mode 100644 index 000000000000..c178af3d82bd --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/init.ts @@ -0,0 +1,20 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +import path from "node:path"; + +import { _dirname } from "./dirname.cjs"; + +export const packageRootPath = path.resolve(_dirname, "../.."); + +/** + * Absolute path to the test data. It's rooted two directories up because the tests get executed from lib/. + */ +export const testDataPath = path.resolve(_dirname, packageRootPath, "src/test/data"); + +/** + * Absolute path to the test repo. + */ +export const testRepoRoot = path.join(testDataPath, "testRepo"); diff --git a/build-tools/packages/build-infrastructure/src/test/tsconfig.cjs.json b/build-tools/packages/build-infrastructure/src/test/tsconfig.cjs.json new file mode 100644 index 000000000000..f966e4a2484f --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/tsconfig.cjs.json @@ -0,0 +1,12 @@ +{ + // This config must be used in a "type": "commonjs" environment. (Use fluid-tsc commonjs.) + "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "../../dist/test", + }, + "references": [ + { + "path": "../../tsconfig.cjs.json", + }, + ], +} diff --git a/build-tools/packages/build-infrastructure/src/test/tsconfig.json b/build-tools/packages/build-infrastructure/src/test/tsconfig.json new file mode 100644 index 000000000000..9661822c0030 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/test/tsconfig.json @@ -0,0 +1,14 @@ +{ + "extends": "../../../../../common/build/build-common/tsconfig.test.node16.json", + "include": ["./**/*"], + "compilerOptions": { + "rootDir": "./", + "outDir": "../../lib/test", + "types": ["node", "mocha", "chai"], + }, + "references": [ + { + "path": "../..", + }, + ], +} diff --git a/build-tools/packages/build-infrastructure/src/types.ts b/build-tools/packages/build-infrastructure/src/types.ts new file mode 100644 index 000000000000..10c24bc4bb71 --- /dev/null +++ b/build-tools/packages/build-infrastructure/src/types.ts @@ -0,0 +1,384 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +import { SimpleGit } from "simple-git"; +import type { Opaque, SetRequired, PackageJson as StandardPackageJson } from "type-fest"; + +import type { IFluidRepoLayout } from "./config.js"; + +/** + * A type representing fluid-build-specific config that may be in package.json. + */ +export interface FluidPackageJsonFields { + /** + * pnpm config + */ + pnpm?: { + overrides?: Record; + }; +} + +export type PackageJson = SetRequired< + StandardPackageJson & FluidPackageJsonFields, + "name" | "scripts" | "version" +>; + +export type AdditionalPackageProps = Record | undefined; + +/** + * A Fluid repo organizes a collection of npm packages into workspaces and release groups. A Fluid repo can contain + * multiple workspaces, and a workspace can in turn contain multiple release groups. Both workspaces and release groups + * represent ways to organize packages in the repo, but their purpose and function are different. + * + * See {@link IWorkspace} and {@link IReleaseGroup} for more details. + */ +export interface IFluidRepo

extends Reloadable { + /** + * The absolute path to the root of the IFluidRepo. This is the path where the config file is located. + */ + root: string; + + /** + * A map of all workspaces in the Fluid repo. + */ + workspaces: Map; + + /** + * A map of all release groups in the Fluid repo. + */ + releaseGroups: Map; + + /** + * A map of all packages in the Fluid repo. + */ + packages: Map; + + /** + * A partial URL to the upstream (remote) repo. This can be set to the name of the repo on GitHub. For example, + * "microsoft/FluidFramework". + */ + upstreamRemotePartialUrl?: string; + + /** + * The layout configuration for the repo. + */ + configuration: IFluidRepoLayout; + + /** + * Transforms an absolute path to a path relative to the FluidRepo root. + * + * @param p - The path to make relative to the FluidRepo root. + * @returns the relative path. + */ + relativeToRepo(p: string): string; + + /** + * If the FluidRepo is within a Git repository, this function will return a SimpleGit instance rooted at the root of + * the Git repository. If the FluidRepo is _not_ within a Git repository, this function will throw a + * {@link NotInGitRepository} error. + * + * @throws A {@link NotInGitRepository} error if the path is not within a Git repository. + */ + getGitRepository(): Promise>; + + /** + * Returns the {@link IReleaseGroup} associated with a package. + */ + getPackageReleaseGroup(pkg: Readonly

): Readonly; + + /** + * Returns the {@link IWorkspace} associated with a package. + */ + getPackageWorkspace(pkg: Readonly

): Readonly; +} + +/** + * A common interface for installable things, like packages, release groups, and workspaces. + */ +export interface Installable { + /** + * Returns `true` if the item is installed. If this returns `false`, then the `install` function can be called to + * install. + */ + checkInstall(): Promise; + + /** + * Installs the item. + * + * @param updateLockfile - If true, the lockfile will be updated. Otherwise, the lockfile will not be updated. This + * may cause the installation to fail. + */ + install(updateLockfile: boolean): Promise; +} + +/** + * An interface for things that can be reloaded, + */ +export interface Reloadable { + reload(): void; +} + +/** + * A tagged type representing workspace names. + */ +export type WorkspaceName = Opaque; + +/** + * A workspace is a collection of packages, including a root package, that is managed using a package manager's + * "workspaces" functionality. A Fluid repo can contain multiple workspaces. Workspaces are defined and managed using + * the package manager directly. A Fluid repo builds on top of workspaces and relies on the package manager to install + * and manage dependencies and interdependencies within the workspace. + * + * A workspace defines the _physical layout_ of the packages within it. Workspaces are a generally a feature provided by + * the package manager (npm, yarn, pnpm, etc.). A workspace is rooted in a particular folder, and uses the configuration + * within that folder to determine what packages it contains. The configuration used is specific to the package manager. + * + * The workspace is also the boundary at which dependencies are installed and managed. When you install dependencies for + * a package in a workspace, all dependencies for all packages in the workspace will be installed. Within a workspace, + * it is trivial to link multiple packages so they can depend on one another. The `IWorkspace` type is a thin wrapper on + * top of these package manager features. + * + * A Fluid repo will only load packages identified by the package manager's workspace feature. That is, any package in + * the repo that is not configured as part of a workspace is invisible to tools using the Fluid repo. + * + * Workspaces are not involved in versioning or releasing packages. They are used for dependency management only. + * Release groups, on the other hand, are used to group packages into releasable groups. See {@link IReleaseGroup} for + * more information. + */ +export interface IWorkspace extends Installable, Reloadable { + /** + * The name of the workspace. + */ + name: WorkspaceName; + + /** + * The root directory of the workspace. This directory will contain the workspace root package. + */ + directory: string; + + /** + * The root package of the workspace. + */ + rootPackage: IPackage; + + /** + * A map of all the release groups in the workspace. + */ + releaseGroups: Map; + + /** + * An array of all the packages in the workspace. This includes the workspace root and any release group roots and + * constituent packages as well. + */ + packages: IPackage[]; + toString(): string; +} + +/** + * A tagged type representing release group names. + */ +export type ReleaseGroupName = Opaque; + +/** + * A release group is a collection of packages that are versioned and released together. All packages within a release + * group will have the same version, and all packages will be released at the same time. + * + * Release groups are not involved in dependency management. They are used for versioning and releasing packages only. + * Workspaces, on the other hand, are used to manage dependencies and interdependencies. See {@link IWorkspace} for more + * information. + */ +export interface IReleaseGroup extends Reloadable { + /** + * The name of the release group. All release groups must have unique names. + */ + readonly name: ReleaseGroupName; + + /** + * The version of the release group. + */ + readonly version: string; + + /** + * The package that is the release group root, if one exists. + */ + readonly rootPackage?: IPackage; + + /** + * An array of all packages in the release group. + */ + readonly packages: IPackage[]; + + /** + * The workspace that the release group belongs to. + */ + readonly workspace: IWorkspace; + + /** + * An array of all the release groups that the release group depends on. If any package in a release group has any + * dependency on a package in another release group within the same workspace, then the first release group depends + * on the second. + */ + readonly releaseGroupDependencies: IReleaseGroup[]; + + /** + * An optional ADO pipeline URL for the CI pipeline that builds the release group. + */ + readonly adoPipelineUrl?: string; + + toString(): string; +} + +/** + * A type guard that returns `true` if the checked item is an {@link IReleaseGroup}. + */ +export function isIReleaseGroup( + // eslint-disable-next-line @typescript-eslint/no-explicit-any + toCheck: Exclude, +): toCheck is IReleaseGroup { + if (!("name" in toCheck)) { + return false; + } + + if (typeof toCheck === "object") { + // TODO: is there a better way to implement a type guard than unique names of properties? Maybe something with the + // opaque types? + return "workspace" in toCheck && "packages" in toCheck; + } + + return false; +} + +/** + * Known package managers supported by build-infrastructure. + */ +export type PackageManagerName = "npm" | "pnpm" | "yarn"; + +/** + * A package manager, such as "npm" or "pnpm". + */ +export interface IPackageManager { + readonly name: PackageManagerName; + readonly lockfileName: string; + installCommand(updateLockfile: boolean): string; +} +/** + * Information about a package dependency. + */ +export interface PackageDependency { + name: PackageName; + version: string; + depClass: "prod" | "dev" | "peer"; +} + +/** + * A tagged type representing package names. + */ +export type PackageName = Opaque; + +/** + * A common type representing an npm package. A custom type can be used for the package.json schema, which is useful + * when the package.json has custom keys/values. + */ +export interface IPackage + extends Installable, + Reloadable { + /** + * The name of the package + */ + readonly name: PackageName; + + /** + * The name of the package color-coded with ANSI color codes for terminal output. The package name will always have + * the same color. + */ + readonly nameColored: string; + + /** + * The absolute path to the directory containing the package (that is, the directory that contains the package.json + * for the package). + */ + readonly directory: string; + + /** + * The package.json contents of the package. + */ + packageJson: J; + + /** + * The package manager used to manage this package. + * + * @privateRemarks + * + * If this is needed at the package level, perhaps it should instead be retrieved from the package's workspace, + * since the package manager is defined at the workspace level. + */ + readonly packageManager: IPackageManager; + + /** + * The version of the package. This is the same as `packageJson.version`. + */ + readonly version: string; + + /** + * `true` if the package is private; `false` otherwise. This is similar to the field in package.json, but always + * returns a boolean value. If the package.json is missing the `private` field, this will return false. + */ + readonly private: boolean; + + /** + * The workspace that this package belongs to. + */ + readonly workspace: IWorkspace; + + /** + * Whether the package is a workspace root package or not. A workspace will only have one root package. + */ + readonly isWorkspaceRoot: boolean; + + /** + * The name of the release group that this package belongs to. + */ + releaseGroup: ReleaseGroupName; + + /** + * Whether the package is a release group root package or not. A release group may not have a root package, but if it + * does, it will only have one. + */ + isReleaseGroupRoot: boolean; + + /** + * The absolute path to the package.json file for this package. + */ + readonly packageJsonFilePath: string; + + /** + * Returns the value of a script in the package's package.json, or undefined if a script with the provided key is not + * found. + */ + getScript(name: string): string | undefined; + + /** + * Saves any changes to the packageJson property to the package.json file on disk. + */ + savePackageJson(): Promise; + + /** + * A generator that returns each dependency and the kind of dependency (dev, peer, etc.) for all of the package's + * dependencies. This is useful to iterate overall all dependencies of the package. + */ + combinedDependencies: Generator; + toString(): string; +} + +/** + * A type guard that returns `true` if the item is an {@link IPackage}. + */ +// eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types -- this is a type guard +export function isIPackage(pkg: any): pkg is IPackage { + if (typeof pkg === "object") { + return "getScript" in pkg; + } + return false; +} diff --git a/build-tools/packages/build-infrastructure/tsconfig.cjs.json b/build-tools/packages/build-infrastructure/tsconfig.cjs.json new file mode 100644 index 000000000000..773d0806da58 --- /dev/null +++ b/build-tools/packages/build-infrastructure/tsconfig.cjs.json @@ -0,0 +1,7 @@ +{ + // This config must be used in a "type": "commonjs" environment. (Use fluid-tsc commonjs.) + "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "./dist", + }, +} diff --git a/build-tools/packages/build-infrastructure/tsconfig.json b/build-tools/packages/build-infrastructure/tsconfig.json new file mode 100644 index 000000000000..18136679b31a --- /dev/null +++ b/build-tools/packages/build-infrastructure/tsconfig.json @@ -0,0 +1,12 @@ +{ + "extends": "../../../common/build/build-common/tsconfig.node16.json", + "include": ["src/**/*"], + "exclude": ["src/test/**/*"], + "compilerOptions": { + "rootDir": "./src", + "outDir": "./lib", + "types": ["node"], + "exactOptionalPropertyTypes": false, + "noUnusedLocals": false, + }, +} diff --git a/build-tools/packages/build-infrastructure/typedoc.config.cjs b/build-tools/packages/build-infrastructure/typedoc.config.cjs new file mode 100644 index 000000000000..c9b2c53b602b --- /dev/null +++ b/build-tools/packages/build-infrastructure/typedoc.config.cjs @@ -0,0 +1,30 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +// Enable TypeScript type-checking for this file. +// See https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#ts-check +// @ts-check + +/** @type {import('typedoc').TypeDocOptions} */ +module.exports = { + entryPoints: ["./src/index.ts"], + plugin: ["typedoc-plugin-markdown"], + gitRevision: "main", + sourceLinkTemplate: + "https://github.com/microsoft/FluidFramework/blob/{gitRevision}/{path}#L{line}", + outputFileStrategy: "members", + out: "docs", + readme: "./README.md", + mergeReadme: true, + // projectDocuments: ["./src/docs/cli.md"], + defaultCategory: "API", + categorizeByGroup: true, + navigation: { + includeCategories: false, + includeGroups: false, + includeFolders: false, + }, + useCodeBlocks: true, +}; diff --git a/build-tools/pnpm-lock.yaml b/build-tools/pnpm-lock.yaml index a9e2d2682e21..42c16bd6035c 100644 --- a/build-tools/pnpm-lock.yaml +++ b/build-tools/pnpm-lock.yaml @@ -47,7 +47,7 @@ importers: version: 7.22.24 '@microsoft/api-extractor': specifier: ^7.45.1 - version: 7.45.1(@types/node@18.18.6) + version: 7.45.1 c8: specifier: ^7.14.0 version: 7.14.0 @@ -398,6 +398,142 @@ importers: specifier: ~5.4.5 version: 5.4.5 + packages/build-infrastructure: + dependencies: + '@fluid-tools/version-tools': + specifier: workspace:^ + version: link:../version-tools + '@manypkg/get-packages': + specifier: ^2.2.0 + version: 2.2.0 + '@oclif/core': + specifier: ^4.0.14 + version: 4.0.14 + cosmiconfig: + specifier: ^8.3.6 + version: 8.3.6(typescript@5.4.5) + detect-indent: + specifier: ^6.1.0 + version: 6.1.0 + execa: + specifier: ^5.1.1 + version: 5.1.1 + fs-extra: + specifier: ^11.2.0 + version: 11.2.0 + globby: + specifier: ^11.1.0 + version: 11.1.0 + micromatch: + specifier: ^4.0.8 + version: 4.0.8 + oclif: + specifier: ^4.14.9 + version: 4.14.9 + picocolors: + specifier: ^1.1.0 + version: 1.1.0 + read-pkg-up: + specifier: ^7.0.1 + version: 7.0.1 + semver: + specifier: ^7.5.4 + version: 7.6.2 + simple-git: + specifier: ^3.19.1 + version: 3.19.1 + sort-package-json: + specifier: 1.57.0 + version: 1.57.0 + type-fest: + specifier: ^2.19.0 + version: 2.19.0 + typescript: + specifier: ~5.4.5 + version: 5.4.5 + devDependencies: + '@biomejs/biome': + specifier: ~1.9.3 + version: 1.9.3 + '@fluid-tools/api-markdown-documenter': + specifier: ^0.17.1 + version: 0.17.1(@types/node@18.18.7) + '@fluidframework/build-common': + specifier: ^2.0.3 + version: 2.0.3 + '@fluidframework/build-tools-bin': + specifier: npm:@fluidframework/build-tools@~0.44.0 + version: /@fluidframework/build-tools@0.44.0 + '@fluidframework/eslint-config-fluid': + specifier: ^5.3.0 + version: 5.3.0(eslint@8.57.0)(typescript@5.4.5) + '@microsoft/api-extractor': + specifier: ^7.45.1 + version: 7.45.1(@types/node@18.18.7) + '@types/chai': + specifier: ^4.3.5 + version: 4.3.5 + '@types/chai-arrays': + specifier: ^2.0.0 + version: 2.0.0 + '@types/fs-extra': + specifier: ^11.0.4 + version: 11.0.4 + '@types/micromatch': + specifier: ^4.0.9 + version: 4.0.9 + '@types/mocha': + specifier: ^9.1.1 + version: 9.1.1 + '@types/node': + specifier: ^18.18.6 + version: 18.18.7 + '@types/semver': + specifier: ^7.5.0 + version: 7.5.0 + c8: + specifier: ^7.14.0 + version: 7.14.0 + chai: + specifier: ^4.3.7 + version: 4.4.1 + chai-arrays: + specifier: ^2.2.0 + version: 2.2.0 + concurrently: + specifier: ^8.2.1 + version: 8.2.1 + copyfiles: + specifier: ^2.4.1 + version: 2.4.1 + eslint: + specifier: ~8.57.0 + version: 8.57.0 + eslint-plugin-chai-friendly: + specifier: ~1.0.1 + version: 1.0.1(eslint@8.57.0) + memfs: + specifier: ^4.14.0 + version: 4.14.0 + mocha: + specifier: ^10.2.0 + version: 10.2.0 + rimraf: + specifier: ^4.4.1 + version: 4.4.1 + ts-node: + specifier: ^10.9.1 + version: 10.9.1(@types/node@18.18.7)(typescript@5.4.5) + typedoc: + specifier: ^0.26.10 + version: 0.26.10(typescript@5.4.5) + typedoc-plugin-markdown: + specifier: ^4.2.9 + version: 4.2.9(typedoc@0.26.10) + unionfs: + specifier: ^4.5.4 + version: 4.5.4 + packages/build-tools: dependencies: '@fluid-tools/version-tools': @@ -1159,6 +1295,23 @@ packages: - typescript dev: true + /@fluid-tools/api-markdown-documenter@0.17.1(@types/node@18.18.7): + resolution: {integrity: sha512-GP9OlzEcvqDJTN77V6KYf774uoG7i2hIIwcsLC94rmBbC51ckjjkyaMZFslqUB6OyOohbkrBJY9I0Wf/2wyaNw==} + dependencies: + '@microsoft/api-extractor-model': 7.28.21(@types/node@18.18.7) + '@microsoft/tsdoc': 0.14.2 + '@rushstack/node-core-library': 3.59.5(@types/node@18.18.7) + chalk: 4.1.2 + hast-util-format: 1.1.0 + hast-util-from-html: 2.0.3 + hast-util-raw: 9.0.4 + hast-util-to-html: 9.0.3 + hastscript: 9.0.0 + unist-util-remove-position: 5.0.0 + transitivePeerDependencies: + - '@types/node' + dev: true + /@fluid-tools/build-cli@0.44.0: resolution: {integrity: sha512-VQSRxRFtvr3BbWkJ/Lu6uHmIXVrwJalFNrX/OiqokrdrC1KUAprzEVMsvqNLuNvhlvD4e4LWohx9TjRWiaQIlg==} engines: {node: '>=18.17.1'} @@ -1168,14 +1321,14 @@ packages: '@fluid-tools/version-tools': 0.44.0 '@fluidframework/build-tools': 0.44.0 '@fluidframework/bundle-size-tools': 0.44.0 - '@microsoft/api-extractor': 7.45.1(@types/node@18.18.6) + '@microsoft/api-extractor': 7.45.1 '@oclif/core': 4.0.14 '@oclif/plugin-autocomplete': 3.1.9 '@oclif/plugin-commands': 4.0.9 '@oclif/plugin-help': 6.2.7 '@oclif/plugin-not-found': 3.2.13 '@octokit/core': 4.2.4 - '@rushstack/node-core-library': 3.59.5(@types/node@18.18.6) + '@rushstack/node-core-library': 3.59.5(@types/node@18.18.7) async: 3.2.4 chalk: 5.3.0 change-case: 3.1.0 @@ -1692,6 +1845,37 @@ packages: resolution: {integrity: sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==} dev: true + /@jsonjoy.com/base64@1.1.2(tslib@2.6.2): + resolution: {integrity: sha512-q6XAnWQDIMA3+FTiOYajoYqySkO+JSat0ytXGSuRdq9uXE7o92gzuQwQM14xaCRlBLGq3v5miDGC4vkVTn54xA==} + engines: {node: '>=10.0'} + peerDependencies: + tslib: '2' + dependencies: + tslib: 2.6.2 + dev: true + + /@jsonjoy.com/json-pack@1.1.0(tslib@2.6.2): + resolution: {integrity: sha512-zlQONA+msXPPwHWZMKFVS78ewFczIll5lXiVPwFPCZUsrOKdxc2AvxU1HoNBmMRhqDZUR9HkC3UOm+6pME6Xsg==} + engines: {node: '>=10.0'} + peerDependencies: + tslib: '2' + dependencies: + '@jsonjoy.com/base64': 1.1.2(tslib@2.6.2) + '@jsonjoy.com/util': 1.5.0(tslib@2.6.2) + hyperdyperid: 1.2.0 + thingies: 1.21.0(tslib@2.6.2) + tslib: 2.6.2 + dev: true + + /@jsonjoy.com/util@1.5.0(tslib@2.6.2): + resolution: {integrity: sha512-ojoNsrIuPI9g6o8UxhraZQSyF2ByJanAY4cTFbc8Mf2AXEF4aQRGY1dJxyJpuyav8r9FGflEt/Ff3u5Nt6YMPA==} + engines: {node: '>=10.0'} + peerDependencies: + tslib: '2' + dependencies: + tslib: 2.6.2 + dev: true + /@kwsites/file-exists@1.1.1: resolution: {integrity: sha512-m9/5YGR18lIwxSFDwfE3oA7bWuq9kdau6ugN4H2rJeyhFQZcG9AgSHkQtSD15a8WvTgfz9aikZMrKPHvbpqFiw==} dependencies: @@ -1733,7 +1917,7 @@ packages: dependencies: '@microsoft/api-extractor-model': 7.27.4 '@microsoft/tsdoc': 0.14.2 - '@rushstack/node-core-library': 3.59.5(@types/node@18.18.6) + '@rushstack/node-core-library': 3.59.5(@types/node@18.18.7) '@rushstack/ts-command-line': 4.15.1 colors: 1.2.5 js-yaml: 3.13.1 @@ -1747,7 +1931,7 @@ packages: dependencies: '@microsoft/tsdoc': 0.14.2 '@microsoft/tsdoc-config': 0.16.2 - '@rushstack/node-core-library': 3.59.5(@types/node@18.18.6) + '@rushstack/node-core-library': 3.59.5(@types/node@18.18.7) transitivePeerDependencies: - '@types/node' dev: true @@ -1761,6 +1945,37 @@ packages: transitivePeerDependencies: - '@types/node' + /@microsoft/api-extractor-model@7.28.21(@types/node@18.18.7): + resolution: {integrity: sha512-AZSdhK/vO4ddukfheXZmrkI5180XLeAqwzu/5pTsJHsXYSyNt3H3VJyynUYKMeNcveG9QLgljH3XRr/LqEfC0Q==} + dependencies: + '@microsoft/tsdoc': 0.14.2 + '@microsoft/tsdoc-config': 0.16.2 + '@rushstack/node-core-library': 5.3.0(@types/node@18.18.7) + transitivePeerDependencies: + - '@types/node' + dev: true + + /@microsoft/api-extractor@7.45.1: + resolution: {integrity: sha512-FZgcJxEmHA15gxTb1PpXHTforRcyIOLp6GKMqqk+ok8M58QJ0y54Bk+dcTcBC92nmanZppKn5/VRXPP4XvzB3Q==} + hasBin: true + dependencies: + '@microsoft/api-extractor-model': 7.28.21(@types/node@18.18.7) + '@microsoft/tsdoc': 0.14.2 + '@microsoft/tsdoc-config': 0.16.2 + '@rushstack/node-core-library': 5.3.0(@types/node@18.18.7) + '@rushstack/rig-package': 0.5.2 + '@rushstack/terminal': 0.12.2(@types/node@18.18.7) + '@rushstack/ts-command-line': 4.21.4 + lodash: 4.17.21 + minimatch: 3.0.8 + resolve: 1.22.8 + semver: 7.5.4 + source-map: 0.6.1 + typescript: 5.4.2 + transitivePeerDependencies: + - '@types/node' + dev: true + /@microsoft/api-extractor@7.45.1(@types/node@18.18.6): resolution: {integrity: sha512-FZgcJxEmHA15gxTb1PpXHTforRcyIOLp6GKMqqk+ok8M58QJ0y54Bk+dcTcBC92nmanZppKn5/VRXPP4XvzB3Q==} hasBin: true @@ -1781,6 +1996,27 @@ packages: transitivePeerDependencies: - '@types/node' + /@microsoft/api-extractor@7.45.1(@types/node@18.18.7): + resolution: {integrity: sha512-FZgcJxEmHA15gxTb1PpXHTforRcyIOLp6GKMqqk+ok8M58QJ0y54Bk+dcTcBC92nmanZppKn5/VRXPP4XvzB3Q==} + hasBin: true + dependencies: + '@microsoft/api-extractor-model': 7.28.21(@types/node@18.18.7) + '@microsoft/tsdoc': 0.14.2 + '@microsoft/tsdoc-config': 0.16.2 + '@rushstack/node-core-library': 5.3.0(@types/node@18.18.7) + '@rushstack/rig-package': 0.5.2 + '@rushstack/terminal': 0.12.2(@types/node@18.18.7) + '@rushstack/ts-command-line': 4.21.4(@types/node@18.18.7) + lodash: 4.17.21 + minimatch: 3.0.8 + resolve: 1.22.8 + semver: 7.5.4 + source-map: 0.6.1 + typescript: 5.4.2 + transitivePeerDependencies: + - '@types/node' + dev: true + /@microsoft/tsdoc-config@0.16.2: resolution: {integrity: sha512-OGiIzzoBLgWWR0UdRJX98oYO+XKGf7tiK4Zk6tQ/E4IJqGCe7dvkTvgDZV5cFJUzLGDOjeAXrnZoA6QkVySuxw==} dependencies: @@ -2324,6 +2560,25 @@ packages: resolve: 1.22.1 semver: 7.3.8 z-schema: 5.0.5 + dev: false + + /@rushstack/node-core-library@3.59.5(@types/node@18.18.7): + resolution: {integrity: sha512-1IpV7LufrI1EoVO8hYsb3t6L8L+yp40Sa0OaOV2CIu1zx4e6ZeVNaVIEXFgMXBKdGXkAh21MnCaIzlDNpG6ZQw==} + peerDependencies: + '@types/node': '*' + peerDependenciesMeta: + '@types/node': + optional: true + dependencies: + '@types/node': 18.18.7 + colors: 1.2.5 + fs-extra: 7.0.1 + import-lazy: 4.0.0 + jju: 1.4.0 + resolve: 1.22.8 + semver: 7.3.8 + z-schema: 5.0.5 + dev: true /@rushstack/node-core-library@5.3.0(@types/node@18.18.6): resolution: {integrity: sha512-t23gjdZV6aWkbwXSE3TkKr1UXJFbXICvAOJ0MRQEB/ZYGhfSJqqrQFaGd20I1a/nIIHJEkNO0xzycHixjcbCPw==} @@ -2343,6 +2598,25 @@ packages: resolve: 1.22.8 semver: 7.5.4 + /@rushstack/node-core-library@5.3.0(@types/node@18.18.7): + resolution: {integrity: sha512-t23gjdZV6aWkbwXSE3TkKr1UXJFbXICvAOJ0MRQEB/ZYGhfSJqqrQFaGd20I1a/nIIHJEkNO0xzycHixjcbCPw==} + peerDependencies: + '@types/node': '*' + peerDependenciesMeta: + '@types/node': + optional: true + dependencies: + '@types/node': 18.18.7 + ajv: 8.13.0 + ajv-draft-04: 1.0.0(ajv@8.13.0) + ajv-formats: 3.0.1(ajv@8.13.0) + fs-extra: 7.0.1 + import-lazy: 4.0.0 + jju: 1.4.0 + resolve: 1.22.8 + semver: 7.5.4 + dev: true + /@rushstack/rig-package@0.5.2: resolution: {integrity: sha512-mUDecIJeH3yYGZs2a48k+pbhM6JYwWlgjs2Ca5f2n1G2/kgdgP9D/07oglEGf6mRyXEnazhEENeYTSNDRCwdqA==} dependencies: @@ -2361,6 +2635,19 @@ packages: '@types/node': 18.18.6 supports-color: 8.1.1 + /@rushstack/terminal@0.12.2(@types/node@18.18.7): + resolution: {integrity: sha512-yaHKyD/l6Zg34pC5zzc/KdiRBHy8zAH7ZbL3umpDLnvTrZ0SP8MVYZu9xA2lRsGkKfGbv/6gQhyNq4/tRzXH4A==} + peerDependencies: + '@types/node': '*' + peerDependenciesMeta: + '@types/node': + optional: true + dependencies: + '@rushstack/node-core-library': 5.3.0(@types/node@18.18.7) + '@types/node': 18.18.7 + supports-color: 8.1.1 + dev: true + /@rushstack/tree-pattern@0.3.1: resolution: {integrity: sha512-2yn4qTkXZTByQffL3ymS6viYuyZk3YnJT49bopGBlm9Thtyfa7iuFUV6tt+09YIRO1sjmSWILf4dPj6+Dr5YVA==} dev: true @@ -2374,6 +2661,17 @@ packages: string-argv: 0.3.1 dev: true + /@rushstack/ts-command-line@4.21.4: + resolution: {integrity: sha512-3ZjQ11kpQwk/lDQqbmxC8UuU6yD20Sy4uNTWIaBEJ5474hEFEE4cbDOS4F9R4zcyCkkaQYv674K2QTunDF5dsQ==} + dependencies: + '@rushstack/terminal': 0.12.2(@types/node@18.18.7) + '@types/argparse': 1.0.38 + argparse: 1.0.10 + string-argv: 0.3.1 + transitivePeerDependencies: + - '@types/node' + dev: true + /@rushstack/ts-command-line@4.21.4(@types/node@18.18.6): resolution: {integrity: sha512-3ZjQ11kpQwk/lDQqbmxC8UuU6yD20Sy4uNTWIaBEJ5474hEFEE4cbDOS4F9R4zcyCkkaQYv674K2QTunDF5dsQ==} dependencies: @@ -2384,6 +2682,54 @@ packages: transitivePeerDependencies: - '@types/node' + /@rushstack/ts-command-line@4.21.4(@types/node@18.18.7): + resolution: {integrity: sha512-3ZjQ11kpQwk/lDQqbmxC8UuU6yD20Sy4uNTWIaBEJ5474hEFEE4cbDOS4F9R4zcyCkkaQYv674K2QTunDF5dsQ==} + dependencies: + '@rushstack/terminal': 0.12.2(@types/node@18.18.7) + '@types/argparse': 1.0.38 + argparse: 1.0.10 + string-argv: 0.3.1 + transitivePeerDependencies: + - '@types/node' + dev: true + + /@shikijs/core@1.22.0: + resolution: {integrity: sha512-S8sMe4q71TJAW+qG93s5VaiihujRK6rqDFqBnxqvga/3LvqHEnxqBIOPkt//IdXVtHkQWKu4nOQNk0uBGicU7Q==} + dependencies: + '@shikijs/engine-javascript': 1.22.0 + '@shikijs/engine-oniguruma': 1.22.0 + '@shikijs/types': 1.22.0 + '@shikijs/vscode-textmate': 9.3.0 + '@types/hast': 3.0.4 + hast-util-to-html: 9.0.3 + dev: true + + /@shikijs/engine-javascript@1.22.0: + resolution: {integrity: sha512-AeEtF4Gcck2dwBqCFUKYfsCq0s+eEbCEbkUuFou53NZ0sTGnJnJ/05KHQFZxpii5HMXbocV9URYVowOP2wH5kw==} + dependencies: + '@shikijs/types': 1.22.0 + '@shikijs/vscode-textmate': 9.3.0 + oniguruma-to-js: 0.4.3 + dev: true + + /@shikijs/engine-oniguruma@1.22.0: + resolution: {integrity: sha512-5iBVjhu/DYs1HB0BKsRRFipRrD7rqjxlWTj4F2Pf+nQSPqc3kcyqFFeZXnBMzDf0HdqaFVvhDRAGiYNvyLP+Mw==} + dependencies: + '@shikijs/types': 1.22.0 + '@shikijs/vscode-textmate': 9.3.0 + dev: true + + /@shikijs/types@1.22.0: + resolution: {integrity: sha512-Fw/Nr7FGFhlQqHfxzZY8Cwtwk5E9nKDUgeLjZgt3UuhcM3yJR9xj3ZGNravZZok8XmEZMiYkSMTPlPkULB8nww==} + dependencies: + '@shikijs/vscode-textmate': 9.3.0 + '@types/hast': 3.0.4 + dev: true + + /@shikijs/vscode-textmate@9.3.0: + resolution: {integrity: sha512-jn7/7ky30idSkd/O5yDBfAnVt+JJpepofP/POZ1iMOxK59cOfqIgg/Dj0eFsjOTMw+4ycJN0uhZH/Eb0bs/EUA==} + dev: true + /@sigstore/protobuf-specs@0.1.0: resolution: {integrity: sha512-a31EnjuIDSX8IXBUib3cYLDRlPMU36AWX4xS8ysLaNu4ZzUesDiPt83pgrW2X1YLMe5L2HbDyaKK5BrL4cNKaQ==} engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0} @@ -2521,6 +2867,10 @@ packages: resolution: {integrity: sha512-6jSBQQugzyX1aWto0CbvOnmxrU9tMoXfA9gc4IrLEtvr3dTwSg5GLGoWiZnGLI6UG/kqpB3JOQKQrqnhUWGKQA==} dev: true + /@types/braces@3.0.4: + resolution: {integrity: sha512-0WR3b8eaISjEW7RpZnclONaLFDf7buaowRHdqLp4vLj54AsSAYWfh3DRbfiYJY9XDxMgx1B4sE1Afw2PGpuHOA==} + dev: true + /@types/cacheable-request@6.0.3: resolution: {integrity: sha512-IQ3EbTzGxIigb1I3qPZc1rWJnH0BmSKv5QYTalEwweFvyBDLSAe24zP0le/hyi7ecGfZVlIVAg4BZqb8WBwKqw==} dependencies: @@ -2566,6 +2916,12 @@ packages: '@types/minimatch': 3.0.5 '@types/node': 18.18.7 + /@types/hast@3.0.4: + resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==} + dependencies: + '@types/unist': 3.0.3 + dev: true + /@types/http-cache-semantics@4.0.4: resolution: {integrity: sha512-1m0bIFVc7eJWyve9S0RnuRgcQqF/Xd5QsUZAZeQFr1Q3/p9JWoQQEqmVy+DPTNpGXwhgIetAoYF8JSc33q29QA==} @@ -2621,6 +2977,12 @@ packages: dependencies: '@types/unist': 3.0.3 + /@types/micromatch@4.0.9: + resolution: {integrity: sha512-7V+8ncr22h4UoYRLnLXSpTxjQrNUXtWHGeMPRJt1nULXI57G9bIcpyrHlmrQ7QK24EyyuXvYcSSWAM8GA9nqCg==} + dependencies: + '@types/braces': 3.0.4 + dev: true + /@types/minimatch@3.0.5: resolution: {integrity: sha512-Klz949h02Gz2uZCMGwDUSDS1YBlTdDDgbWHi+81l29tQALUtvz4rAYi5uoVhE5Lagoq6DeqAUlbrHvW/mXDgdQ==} @@ -2638,7 +3000,7 @@ packages: /@types/msgpack-lite@0.1.8: resolution: {integrity: sha512-3qIhe8MH1kGcXnB5YuY6W0lLb9LEcWrhanDYfw0zKdXAv+CNKG0+6To1X8dqVyrxKb3FeAgJBJS5RdFwBQteVg==} dependencies: - '@types/node': 18.18.6 + '@types/node': 18.18.7 dev: true /@types/mute-stream@0.0.4: @@ -2696,7 +3058,7 @@ packages: resolution: {integrity: sha512-YyP+VfeaqAyFmXoTh3HChxOQMyjByRMsHU7kc5KOJkSlXudhMhQIALbYV7rHh/l8d2lX3VUQzprrcAgWdRuU8g==} dependencies: '@types/glob': 7.2.0 - '@types/node': 18.18.6 + '@types/node': 18.18.7 dev: true /@types/semver-utils@1.1.1: @@ -2710,7 +3072,7 @@ packages: resolution: {integrity: sha512-ZA8U81/gldY+rR5zl/7HSHrG2KDfEb3lzG6uCUDhW1DTQE9yC/VBQ45fXnXq8f3CgInfhZmjtdu/WOUlrXRQUg==} dependencies: '@types/glob': 7.2.0 - '@types/node': 18.18.6 + '@types/node': 18.18.7 dev: true /@types/sinon@10.0.13: @@ -3935,6 +4297,14 @@ packages: snake-case: 3.0.4 tslib: 2.6.2 + /character-entities-html4@2.1.0: + resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==} + dev: true + + /character-entities-legacy@3.0.0: + resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==} + dev: true + /character-entities@2.0.2: resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==} @@ -4157,6 +4527,10 @@ packages: dependencies: delayed-stream: 1.0.0 + /comma-separated-tokens@2.0.3: + resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==} + dev: true + /command-line-args@4.0.7: resolution: {integrity: sha512-aUdPvQRAyBvQd2n7jXcsMDz68ckBJELXNzBybCHOibUWEg0mWTnaYCSRU8h9R+aNRSvDihJtssSRCiDRpLaezA==} hasBin: true @@ -4976,6 +5350,11 @@ packages: graceful-fs: 4.2.11 tapable: 2.2.1 + /entities@4.5.0: + resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==} + engines: {node: '>=0.12'} + dev: true + /env-paths@2.2.1: resolution: {integrity: sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==} engines: {node: '>=6'} @@ -5225,7 +5604,7 @@ packages: eslint: '*' eslint-plugin-import: '*' dependencies: - debug: 4.3.4(supports-color@8.1.1) + debug: 4.3.5(supports-color@8.1.1) enhanced-resolve: 5.15.0 eslint: 8.57.0 eslint-module-utils: 2.8.0(@typescript-eslint/parser@6.21.0)(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.6.1)(eslint@8.57.0) @@ -5324,6 +5703,15 @@ packages: - supports-color dev: true + /eslint-plugin-chai-friendly@1.0.1(eslint@8.57.0): + resolution: {integrity: sha512-dxD/uz1YKJ8U4yah1i+V/p/u+kHRy3YxTPe2nJGqb5lCR+ucan/KIexfZ5+q4X+tkllyMe86EBbAkdlwxNy3oQ==} + engines: {node: '>=0.10.0'} + peerDependencies: + eslint: '>=3.0.0 || 8.51.0' + dependencies: + eslint: 8.57.0 + dev: true + /eslint-plugin-es@4.1.0(eslint@8.57.0): resolution: {integrity: sha512-GILhQTnjYE2WorX5Jyi5i4dz5ALWxBIdQECVQavL6s7cI76IZTDWleTHkxz/QT3kvcs2QlGHvKLYsSlPOlPXnQ==} engines: {node: '>=8.10.0'} @@ -5803,7 +6191,7 @@ packages: '@nodelib/fs.walk': 1.2.8 glob-parent: 5.1.2 merge2: 1.4.1 - micromatch: 4.0.5 + micromatch: 4.0.8 /fast-json-patch@3.1.1: resolution: {integrity: sha512-vf6IHUX2SBcA+5/+4883dsIjpBTqmfBjmYiWK1savxQmFk4JfBMLa7ynTYOs1Rolp/T1betJxHiGD3g1Mn8lUQ==} @@ -5935,7 +6323,7 @@ packages: /find-yarn-workspace-root@2.0.0: resolution: {integrity: sha512-1IMnbjt4KzsQfnhnzNd8wUEgXZ44IzZaZmnLYx7D5FZlaHt2gW20Cri8Q+E/t5tIj4+epTBub+2Zxu/vNILzqQ==} dependencies: - micromatch: 4.0.5 + micromatch: 4.0.8 /findup-sync@4.0.0: resolution: {integrity: sha512-6jvvn/12IC4quLBL1KNokxC7wWTvYncaVUYSoxWw7YykPLuRrnv4qdHcSOywOI5RpkOVGeQRtWM8/q+G6W6qfQ==} @@ -5943,7 +6331,7 @@ packages: dependencies: detect-file: 1.0.0 is-glob: 4.0.3 - micromatch: 4.0.5 + micromatch: 4.0.8 resolve-dir: 1.0.1 dev: true @@ -6074,6 +6462,10 @@ packages: dependencies: minipass: 5.0.0 + /fs-monkey@1.0.6: + resolution: {integrity: sha512-b1FMfwetIKymC0eioW7mTywihSQE4oLzQn1dB6rZB5fx/3NpNEdAWeCSMB+60/AeT0TCXsxzAlcYVEFCTAksWg==} + dev: true + /fs.realpath@1.0.0: resolution: {integrity: sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==} @@ -6563,6 +6955,165 @@ packages: dependencies: function-bind: 1.1.2 + /hast-util-embedded@3.0.0: + resolution: {integrity: sha512-naH8sld4Pe2ep03qqULEtvYr7EjrLK2QHY8KJR6RJkTUjPGObe1vnx585uzem2hGra+s1q08DZZpfgDVYRbaXA==} + dependencies: + '@types/hast': 3.0.4 + hast-util-is-element: 3.0.0 + dev: true + + /hast-util-format@1.1.0: + resolution: {integrity: sha512-yY1UDz6bC9rDvCWHpx12aIBGRG7krurX0p0Fm6pT547LwDIZZiNr8a+IHDogorAdreULSEzP82Nlv5SZkHZcjA==} + dependencies: + '@types/hast': 3.0.4 + hast-util-embedded: 3.0.0 + hast-util-minify-whitespace: 1.0.1 + hast-util-phrasing: 3.0.1 + hast-util-whitespace: 3.0.0 + html-whitespace-sensitive-tag-names: 3.0.1 + unist-util-visit-parents: 6.0.1 + dev: true + + /hast-util-from-html@2.0.3: + resolution: {integrity: sha512-CUSRHXyKjzHov8yKsQjGOElXy/3EKpyX56ELnkHH34vDVw1N1XSQ1ZcAvTyAPtGqLTuKP/uxM+aLkSPqF/EtMw==} + dependencies: + '@types/hast': 3.0.4 + devlop: 1.1.0 + hast-util-from-parse5: 8.0.1 + parse5: 7.2.0 + vfile: 6.0.2 + vfile-message: 4.0.2 + dev: true + + /hast-util-from-parse5@8.0.1: + resolution: {integrity: sha512-Er/Iixbc7IEa7r/XLtuG52zoqn/b3Xng/w6aZQ0xGVxzhw5xUFxcRqdPzP6yFi/4HBYRaifaI5fQ1RH8n0ZeOQ==} + dependencies: + '@types/hast': 3.0.4 + '@types/unist': 3.0.3 + devlop: 1.1.0 + hastscript: 8.0.0 + property-information: 6.5.0 + vfile: 6.0.2 + vfile-location: 5.0.3 + web-namespaces: 2.0.1 + dev: true + + /hast-util-has-property@3.0.0: + resolution: {integrity: sha512-MNilsvEKLFpV604hwfhVStK0usFY/QmM5zX16bo7EjnAEGofr5YyI37kzopBlZJkHD4t887i+q/C8/tr5Q94cA==} + dependencies: + '@types/hast': 3.0.4 + dev: true + + /hast-util-is-body-ok-link@3.0.1: + resolution: {integrity: sha512-0qpnzOBLztXHbHQenVB8uNuxTnm/QBFUOmdOSsEn7GnBtyY07+ENTWVFBAnXd/zEgd9/SUG3lRY7hSIBWRgGpQ==} + dependencies: + '@types/hast': 3.0.4 + dev: true + + /hast-util-is-element@3.0.0: + resolution: {integrity: sha512-Val9mnv2IWpLbNPqc/pUem+a7Ipj2aHacCwgNfTiK0vJKl0LF+4Ba4+v1oPHFpf3bLYmreq0/l3Gud9S5OH42g==} + dependencies: + '@types/hast': 3.0.4 + dev: true + + /hast-util-minify-whitespace@1.0.1: + resolution: {integrity: sha512-L96fPOVpnclQE0xzdWb/D12VT5FabA7SnZOUMtL1DbXmYiHJMXZvFkIZfiMmTCNJHUeO2K9UYNXoVyfz+QHuOw==} + dependencies: + '@types/hast': 3.0.4 + hast-util-embedded: 3.0.0 + hast-util-is-element: 3.0.0 + hast-util-whitespace: 3.0.0 + unist-util-is: 6.0.0 + dev: true + + /hast-util-parse-selector@4.0.0: + resolution: {integrity: sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==} + dependencies: + '@types/hast': 3.0.4 + dev: true + + /hast-util-phrasing@3.0.1: + resolution: {integrity: sha512-6h60VfI3uBQUxHqTyMymMZnEbNl1XmEGtOxxKYL7stY2o601COo62AWAYBQR9lZbYXYSBoxag8UpPRXK+9fqSQ==} + dependencies: + '@types/hast': 3.0.4 + hast-util-embedded: 3.0.0 + hast-util-has-property: 3.0.0 + hast-util-is-body-ok-link: 3.0.1 + hast-util-is-element: 3.0.0 + dev: true + + /hast-util-raw@9.0.4: + resolution: {integrity: sha512-LHE65TD2YiNsHD3YuXcKPHXPLuYh/gjp12mOfU8jxSrm1f/yJpsb0F/KKljS6U9LJoP0Ux+tCe8iJ2AsPzTdgA==} + dependencies: + '@types/hast': 3.0.4 + '@types/unist': 3.0.3 + '@ungap/structured-clone': 1.2.0 + hast-util-from-parse5: 8.0.1 + hast-util-to-parse5: 8.0.0 + html-void-elements: 3.0.0 + mdast-util-to-hast: 13.2.0 + parse5: 7.2.0 + unist-util-position: 5.0.0 + unist-util-visit: 5.0.0 + vfile: 6.0.2 + web-namespaces: 2.0.1 + zwitch: 2.0.4 + dev: true + + /hast-util-to-html@9.0.3: + resolution: {integrity: sha512-M17uBDzMJ9RPCqLMO92gNNUDuBSq10a25SDBI08iCCxmorf4Yy6sYHK57n9WAbRAAaU+DuR4W6GN9K4DFZesYg==} + dependencies: + '@types/hast': 3.0.4 + '@types/unist': 3.0.3 + ccount: 2.0.1 + comma-separated-tokens: 2.0.3 + hast-util-whitespace: 3.0.0 + html-void-elements: 3.0.0 + mdast-util-to-hast: 13.2.0 + property-information: 6.5.0 + space-separated-tokens: 2.0.2 + stringify-entities: 4.0.4 + zwitch: 2.0.4 + dev: true + + /hast-util-to-parse5@8.0.0: + resolution: {integrity: sha512-3KKrV5ZVI8if87DVSi1vDeByYrkGzg4mEfeu4alwgmmIeARiBLKCZS2uw5Gb6nU9x9Yufyj3iudm6i7nl52PFw==} + dependencies: + '@types/hast': 3.0.4 + comma-separated-tokens: 2.0.3 + devlop: 1.1.0 + property-information: 6.5.0 + space-separated-tokens: 2.0.2 + web-namespaces: 2.0.1 + zwitch: 2.0.4 + dev: true + + /hast-util-whitespace@3.0.0: + resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==} + dependencies: + '@types/hast': 3.0.4 + dev: true + + /hastscript@8.0.0: + resolution: {integrity: sha512-dMOtzCEd3ABUeSIISmrETiKuyydk1w0pa+gE/uormcTpSYuaNJPbX1NU3JLyscSLjwAQM8bWMhhIlnCqnRvDTw==} + dependencies: + '@types/hast': 3.0.4 + comma-separated-tokens: 2.0.3 + hast-util-parse-selector: 4.0.0 + property-information: 6.5.0 + space-separated-tokens: 2.0.2 + dev: true + + /hastscript@9.0.0: + resolution: {integrity: sha512-jzaLBGavEDKHrc5EfFImKN7nZKKBdSLIdGvCwDZ9TfzbF2ffXiov8CKE445L2Z1Ek2t/m4SKQ2j6Ipv7NyUolw==} + dependencies: + '@types/hast': 3.0.4 + comma-separated-tokens: 2.0.3 + hast-util-parse-selector: 4.0.0 + property-information: 6.5.0 + space-separated-tokens: 2.0.2 + dev: true + /he@1.2.0: resolution: {integrity: sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==} hasBin: true @@ -6618,6 +7169,14 @@ packages: resolution: {integrity: sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==} dev: true + /html-void-elements@3.0.0: + resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==} + dev: true + + /html-whitespace-sensitive-tag-names@3.0.1: + resolution: {integrity: sha512-q+310vW8zmymYHALr1da4HyXUQ0zgiIwIicEfotYPWGN0OJVEN/58IJ3A4GBYcEq3LGAZqKb+ugvP0GNB9CEAA==} + dev: true + /http-cache-semantics@4.1.1: resolution: {integrity: sha512-er295DKPVsV82j5kw1Gjt+ADA/XYHsajl82cGNQG2eyoPkvgUhX+nDIyelzhIWbbsXP39EHcI6l5tYs2FYqYXQ==} @@ -6679,6 +7238,11 @@ packages: dependencies: ms: 2.1.3 + /hyperdyperid@1.2.0: + resolution: {integrity: sha512-Y93lCzHYgGWdrJ66yIktxiaGULYc6oGiABxhcO5AufBeOyoIdZF7bIfLaOrbM0iGIOXQQgxxRrFEnb+Y6w1n4A==} + engines: {node: '>=10.18'} + dev: true + /hyperlinker@1.0.0: resolution: {integrity: sha512-Ty8UblRWFEcfSuIaajM34LdPXIhbs1ajEX/BBPv24J+enSVaEVY63xQ6lTO9VRYS5LAoghIG0IDJ+p+IPzKUQQ==} engines: {node: '>=4'} @@ -7466,6 +8030,12 @@ packages: /lines-and-columns@1.2.4: resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==} + /linkify-it@5.0.0: + resolution: {integrity: sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==} + dependencies: + uc.micro: 2.1.0 + dev: true + /load-json-file@4.0.0: resolution: {integrity: sha512-Kx8hMakjX03tiGTLAIdJ+lL0htKnXjEZN6hk/tozf/WOuYGdZBJrZ+rCJRbVCugsjB3jMLn9746NsQIf5VjBMw==} engines: {node: '>=4'} @@ -7691,6 +8261,10 @@ packages: es5-ext: 0.10.64 dev: true + /lunr@2.3.9: + resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} + dev: true + /make-dir@3.1.0: resolution: {integrity: sha512-g3FeP20LNwhALb/6Cz6Dd4F2ngze0jz7tbzrD2wAV+o9FeNHe4rL+yK2md0J/fiSf1sa1ADhXqi5+oVwOM/eGw==} engines: {node: '>=8'} @@ -7758,6 +8332,18 @@ packages: engines: {node: '>=8'} dev: true + /markdown-it@14.1.0: + resolution: {integrity: sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==} + hasBin: true + dependencies: + argparse: 2.0.1 + entities: 4.5.0 + linkify-it: 5.0.0 + mdurl: 2.0.0 + punycode.js: 2.3.1 + uc.micro: 2.1.0 + dev: true + /markdown-table@3.0.3: resolution: {integrity: sha512-Z1NL3Tb1M9wH4XESsCDEksWoKTdlUafKc4pt0GRwjUyXaCFZ+dc3g2erqB6zm3szA2IUSi7VnPI+o/9jnxh9hw==} @@ -7865,6 +8451,20 @@ packages: '@types/mdast': 4.0.4 unist-util-is: 6.0.0 + /mdast-util-to-hast@13.2.0: + resolution: {integrity: sha512-QGYKEuUsYT9ykKBCMOEDLsU5JRObWQusAolFMeko/tYPufNkRffBAQjIE+99jbA87xv6FgmjLtwjh9wBWajwAA==} + dependencies: + '@types/hast': 3.0.4 + '@types/mdast': 4.0.4 + '@ungap/structured-clone': 1.2.0 + devlop: 1.1.0 + micromark-util-sanitize-uri: 2.0.0 + trim-lines: 3.0.1 + unist-util-position: 5.0.0 + unist-util-visit: 5.0.0 + vfile: 6.0.2 + dev: true + /mdast-util-to-markdown@2.1.0: resolution: {integrity: sha512-SR2VnIEdVNCJbP6y7kVTJgPLifdr8WEU440fQec7qHoHOUz/oJ2jmNRqdDQ3rbiStOXb2mCDGTuwsK5OPUgYlQ==} dependencies: @@ -7898,6 +8498,10 @@ packages: deprecated: '`mdast` was renamed to `remark`' dev: false + /mdurl@2.0.0: + resolution: {integrity: sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==} + dev: true + /memfs-or-file-map-to-github-branch@1.2.1: resolution: {integrity: sha512-I/hQzJ2a/pCGR8fkSQ9l5Yx+FQ4e7X6blNHyWBm2ojeFLT3GVzGkTj7xnyWpdclrr7Nq4dmx3xrvu70m3ypzAQ==} dependencies: @@ -7905,6 +8509,16 @@ packages: transitivePeerDependencies: - encoding + /memfs@4.14.0: + resolution: {integrity: sha512-JUeY0F/fQZgIod31Ja1eJgiSxLn7BfQlCnqhwXFBzFHEw63OdLK7VJUJ7bnzNsWgCyoUP5tEp1VRY8rDaYzqOA==} + engines: {node: '>= 4.0.0'} + dependencies: + '@jsonjoy.com/json-pack': 1.1.0(tslib@2.6.2) + '@jsonjoy.com/util': 1.5.0(tslib@2.6.2) + tree-dump: 1.0.2(tslib@2.6.2) + tslib: 2.6.2 + dev: true + /memoizee@0.4.15: resolution: {integrity: sha512-UBWmJpLZd5STPm7PMUlOw/TSy972M+z8gcyQ5veOnSDRREz/0bmpyTfKt3/51DhEBqCZQn1udM/5flcSPYhkdQ==} dependencies: @@ -8172,6 +8786,13 @@ packages: braces: 3.0.3 picomatch: 2.3.1 + /micromatch@4.0.8: + resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==} + engines: {node: '>=8.6'} + dependencies: + braces: 3.0.3 + picomatch: 2.3.1 + /mime-db@1.52.0: resolution: {integrity: sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==} engines: {node: '>= 0.6'} @@ -8883,6 +9504,12 @@ packages: dependencies: mimic-fn: 2.1.0 + /oniguruma-to-js@0.4.3: + resolution: {integrity: sha512-X0jWUcAlxORhOqqBREgPMgnshB7ZGYszBNspP+tS9hPD3l13CdaXcHbgImoHUHlrvGx/7AvFEkTRhAGYh+jzjQ==} + dependencies: + regex: 4.3.3 + dev: true + /optionator@0.9.3: resolution: {integrity: sha512-JjCoypp+jKn1ttEFExxhetCKeJt9zhAgAve5FXHixTvFDW/5aEktX9bufBKLRRMdU7bNtpLfcGu94B3cdEJgjg==} engines: {node: '>= 0.8.0'} @@ -9119,6 +9746,12 @@ packages: resolution: {integrity: sha512-1Y1A//QUXEZK7YKz+rD9WydcE1+EuPr6ZBgKecAB8tmoW6UFv0NREVJe1p+jRxtThkcbbKkfwIbWJe/IeE6m2Q==} engines: {node: '>=0.10.0'} + /parse5@7.2.0: + resolution: {integrity: sha512-ZkDsAOcxsUMZ4Lz5fVciOehNcJ+Gb8gTzcA4yl3wnc273BAybYWrQ+Ks/OjCjSEpjvQkDSeZbybK9qj2VHHdGA==} + dependencies: + entities: 4.5.0 + dev: true + /pascal-case@2.0.1: resolution: {integrity: sha512-qjS4s8rBOJa2Xm0jmxXiyh1+OFf6ekCWOvUaRgAQSktzlTbMotS0nmG9gyYAybCWBcuP4fsBeRCKNwGBnMe2OQ==} dependencies: @@ -9313,6 +9946,10 @@ packages: engines: {node: '>= 8'} dev: true + /property-information@6.5.0: + resolution: {integrity: sha512-PgTgs/BlvHxOu8QuEN7wi5A0OmXaBcHpmCSTehcs6Uuu9IkDIEo13Hy7n898RHfrQ49vKCoGeWZSaAK01nwVig==} + dev: true + /proto-list@1.2.4: resolution: {integrity: sha512-vtK/94akxsTMhe0/cbfpR+syPuszcuwhqVjJq26CuNDgFGj682oRBXOP5MJpv2r7JtE8MsiepGIqvvOTBwn2vA==} @@ -9322,6 +9959,11 @@ packages: end-of-stream: 1.4.4 once: 1.4.0 + /punycode.js@2.3.1: + resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==} + engines: {node: '>=6'} + dev: true + /punycode@2.3.0: resolution: {integrity: sha512-rRV+zQD8tVFys26lAGR9WUuS4iUAngJScM+ZRSKtvl5tKeZ2t5bvdNFdNHBW9FWR4guGHlgmsZ1G7BSm2wTbuA==} engines: {node: '>=6'} @@ -9534,6 +10176,10 @@ packages: /regenerator-runtime@0.13.11: resolution: {integrity: sha512-kY1AZVr2Ra+t+piVaJ4gxaFaReZVH40AKNo7UCX6W+dEwBo/2oZJzqfuN1qLq1oL45o56cPaTXELwrTh8Fpggg==} + /regex@4.3.3: + resolution: {integrity: sha512-r/AadFO7owAq1QJVeZ/nq9jNS1vyZt+6t1p/E59B56Rn2GCya+gr1KSyOzNL/er+r+B7phv5jG2xU2Nz1YkmJg==} + dev: true + /regexp-tree@0.1.27: resolution: {integrity: sha512-iETxpjK6YoRWJG5o6hXLwvjYAoW+FEZn9os0PD/b6AP6xQwsa/Y7lCVgIixBbUPMfhu+i2LtdeAqVTgGlQarfA==} hasBin: true @@ -10025,6 +10671,17 @@ packages: resolution: {integrity: sha512-6j1W9l1iAs/4xYBI1SYOVZyFcCis9b4KCLQ8fgAGG07QvzaRLVVRQvAy85yNmmZSjYjg4MWh4gNvlPujU/5LpA==} dev: true + /shiki@1.22.0: + resolution: {integrity: sha512-/t5LlhNs+UOKQCYBtl5ZsH/Vclz73GIqT2yQsCBygr8L/ppTdmpL4w3kPLoZJbMKVWtoG77Ue1feOjZfDxvMkw==} + dependencies: + '@shikijs/core': 1.22.0 + '@shikijs/engine-javascript': 1.22.0 + '@shikijs/engine-oniguruma': 1.22.0 + '@shikijs/types': 1.22.0 + '@shikijs/vscode-textmate': 9.3.0 + '@types/hast': 3.0.4 + dev: true + /side-channel@1.0.4: resolution: {integrity: sha512-q5XPytqFEIKHkGdiMIrY10mvLRvnQh42/+GoBlFW3b2LXLE2xxJpZFdm94we0BaoV3RwJyGqg5wS7epxTv0Zvw==} dependencies: @@ -10185,6 +10842,10 @@ packages: resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==} engines: {node: '>=0.10.0'} + /space-separated-tokens@2.0.2: + resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==} + dev: true + /spawn-command@0.0.2: resolution: {integrity: sha512-zC8zGoGkmc8J9ndvml8Xksr1Amk9qBujgbF0JAIWO7kXr43w0h/0GJNM/Vustixu+YE8N/MTrQ7N31FvHUACxQ==} dev: true @@ -10344,6 +11005,13 @@ packages: dependencies: safe-buffer: 5.2.1 + /stringify-entities@4.0.4: + resolution: {integrity: sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==} + dependencies: + character-entities-html4: 2.1.0 + character-entities-legacy: 3.0.0 + dev: true + /strip-ansi@4.0.0: resolution: {integrity: sha512-4XaJ2zQdCzROZDivEVIDPkcQn8LMFSa8kj8Gxb/Lnwzv9A8VctNZ+lfivC/sV3ivW8ElJTERXZoPBRrZKkNKow==} engines: {node: '>=4'} @@ -10581,6 +11249,15 @@ packages: txt_tocfill: 0.5.1 dev: true + /thingies@1.21.0(tslib@2.6.2): + resolution: {integrity: sha512-hsqsJsFMsV+aD4s3CWKk85ep/3I9XzYV/IXaSouJMYIoDlgyi11cBhsqYe9/geRfB0YIikBQg6raRaM+nIMP9g==} + engines: {node: '>=10.18'} + peerDependencies: + tslib: ^2 + dependencies: + tslib: 2.6.2 + dev: true + /through2@2.0.5: resolution: {integrity: sha512-/mrRod8xqpA+IHSLyGCQ2s8SPHiCDEeQJSep1jqLYeEUClOFG2Qsh+4FU6G9VeqpZnGW/Su8LQGc4YKni5rYSQ==} dependencies: @@ -10643,11 +11320,24 @@ packages: /tr46@0.0.3: resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==} + /tree-dump@1.0.2(tslib@2.6.2): + resolution: {integrity: sha512-dpev9ABuLWdEubk+cIaI9cHwRNNDjkBBLXTwI4UCUFdQ5xXKqNXoK4FEciw/vxf+NQ7Cb7sGUyeUtORvHIdRXQ==} + engines: {node: '>=10.0'} + peerDependencies: + tslib: '2' + dependencies: + tslib: 2.6.2 + dev: true + /tree-kill@1.2.2: resolution: {integrity: sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==} hasBin: true dev: true + /trim-lines@3.0.1: + resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==} + dev: true + /trim-newlines@3.0.1: resolution: {integrity: sha512-c1PTsA3tYrIsLGkJkzHF+w9F2EyxfXGo4UyJc4pFL++FMjnq0HJS69T3M7d//gKrFKwy429bouPescbjecU+Zw==} engines: {node: '>=8'} @@ -10910,6 +11600,30 @@ packages: dependencies: is-typedarray: 1.0.0 + /typedoc-plugin-markdown@4.2.9(typedoc@0.26.10): + resolution: {integrity: sha512-Wqmx+7ezKFgtTklEq/iUhQ5uFeBDhAT6wiS2na9cFLidIpl9jpDHJy/COYh8jUZXgIRIZVQ/bPNjyrnPFoDwzg==} + engines: {node: '>= 18'} + peerDependencies: + typedoc: 0.26.x + dependencies: + typedoc: 0.26.10(typescript@5.4.5) + dev: true + + /typedoc@0.26.10(typescript@5.4.5): + resolution: {integrity: sha512-xLmVKJ8S21t+JeuQLNueebEuTVphx6IrP06CdV7+0WVflUSW3SPmR+h1fnWVdAR/FQePEgsSWCUHXqKKjzuUAw==} + engines: {node: '>= 18'} + hasBin: true + peerDependencies: + typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x + dependencies: + lunr: 2.3.9 + markdown-it: 14.1.0 + minimatch: 9.0.5 + shiki: 1.22.0 + typescript: 5.4.5 + yaml: 2.6.0 + dev: true + /typescript@5.4.2: resolution: {integrity: sha512-+2/g0Fds1ERlP6JsakQQDXjZdZMM+rqpamFZJEKh4kwTIn3iDkgKtby0CeNd5ATNZ4Ry1ax15TMx0W2V+miizQ==} engines: {node: '>=14.17'} @@ -10924,6 +11638,10 @@ packages: resolution: {integrity: sha512-ofhi8kjIje6npGozTip9Fr8iecmYfEbS06i0JnIg+rh51KakryWF4+jX8lLKZVhy6N+ID45WYSFCxPOdTWCzNg==} dev: true + /uc.micro@2.1.0: + resolution: {integrity: sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==} + dev: true + /uglify-js@3.17.4: resolution: {integrity: sha512-T9q82TJI9e/C1TAxYvfb16xO120tMVFZrGA3f9/P4424DNu6ypK103y0GPFVa17yotwSyZW5iYXgjYHkGrJW/g==} engines: {node: '>=0.8.0'} @@ -10961,6 +11679,12 @@ packages: trough: 2.2.0 vfile: 6.0.2 + /unionfs@4.5.4: + resolution: {integrity: sha512-qI3RvJwwdFcWUdZz1dWgAyLSfGlY2fS2pstvwkZBUTnkxjcnIvzriBLtqJTKz9FtArAvJeiVCqHlxhOw8Syfyw==} + dependencies: + fs-monkey: 1.0.6 + dev: true + /unique-filename@2.0.1: resolution: {integrity: sha512-ODWHtkkdx3IAR+veKxFV+VBkUMcN+FaqzUUd7IZzt+0zhDZFPFxhlqwPF3YQvMHx1TD0tdgYl+kuPnJ8E6ql7A==} engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0} @@ -10996,6 +11720,19 @@ packages: dependencies: '@types/unist': 3.0.3 + /unist-util-position@5.0.0: + resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==} + dependencies: + '@types/unist': 3.0.3 + dev: true + + /unist-util-remove-position@5.0.0: + resolution: {integrity: sha512-Hp5Kh3wLxv0PHj9m2yZhhLt58KzPtEYKQQ4yxfYFEO7EvHwzyDYnduhHnY1mDxoqr7VUwVuHXk9RXKIiYS1N8Q==} + dependencies: + '@types/unist': 3.0.3 + unist-util-visit: 5.0.0 + dev: true + /unist-util-stringify-position@4.0.0: resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==} dependencies: @@ -11135,6 +11872,13 @@ packages: resolution: {integrity: sha512-B+dGG8U3fdtM0/aNK4/X8CXq/EcxU2WPrPEkJGslb47qyHsxmbggTWK0yEA4qnYVNF+nxNlN88o14hIcPmSIEA==} engines: {node: '>= 0.10'} + /vfile-location@5.0.3: + resolution: {integrity: sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==} + dependencies: + '@types/unist': 3.0.3 + vfile: 6.0.2 + dev: true + /vfile-message@4.0.2: resolution: {integrity: sha512-jRDZ1IMLttGj41KcZvlrYAaI3CfqpLpfpf+Mfig13viT6NKvRzWZ+lXz0Y5D60w6uJIBAOGq9mSHf0gktF0duw==} dependencies: @@ -11160,6 +11904,10 @@ packages: dependencies: defaults: 1.0.3 + /web-namespaces@2.0.1: + resolution: {integrity: sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==} + dev: true + /web-streams-polyfill@3.3.3: resolution: {integrity: sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==} engines: {node: '>= 8'} @@ -11387,6 +12135,12 @@ packages: resolution: {integrity: sha512-2eHWfjaoXgTBC2jNM1LRef62VQa0umtvRiDSk6HSzW7RvS5YtkabJrwYLLEKWBc8a5U2PTSCs+dJjUTJdlHsWQ==} engines: {node: '>= 14'} + /yaml@2.6.0: + resolution: {integrity: sha512-a6ae//JvKDEra2kdi1qzCyrJW/WZCgFi8ydDV+eXExl95t+5R+ijnqHJbz9tmMh8FUjx3iv2fCQ4dclAQlO2UQ==} + engines: {node: '>= 14'} + hasBin: true + dev: true + /yargs-parser@18.1.3: resolution: {integrity: sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==} engines: {node: '>=6'} diff --git a/fluidBuild.config.cjs b/fluidBuild.config.cjs index 747603961590..98c07690948e 100644 --- a/fluidBuild.config.cjs +++ b/fluidBuild.config.cjs @@ -433,6 +433,14 @@ module.exports = { "package.json", ], "npm-package-json-script-dep": [], + "npm-package-license": [ + // test packages + "^build-tools/packages/build-infrastructure/src/test/data/testRepo/", + ], + "npm-private-packages": [ + // test packages + "^build-tools/packages/build-infrastructure/src/test/data/testRepo/", + ], "npm-public-package-requirements": [ // Test packages published only for the purpose of running tests in CI. "^azure/packages/test/", @@ -462,6 +470,10 @@ module.exports = { "^tools/telemetry-generator/", "^packages/tools/webpack-fluid-loader/", ], + "pnpm-npm-package-json-preinstall": [ + // test packages + "^build-tools/packages/build-infrastructure/src/test/data/testRepo/", + ], }, packageNames: { // The allowed package scopes for the repo. From 8a6db1d9f215949e4b5fc0478b0469ffb2d4cef9 Mon Sep 17 00:00:00 2001 From: Tyler Butler Date: Tue, 22 Oct 2024 09:15:30 -0700 Subject: [PATCH 2/5] docs --- .../api-report/build-infrastructure.api.md | 20 ++---- .../build-infrastructure/docs/README.md | 13 ++-- .../docs/functions/getFluidRepoLayout.md | 2 +- .../docs/functions/isIPackage.md | 2 +- .../docs/functions/isIReleaseGroup.md | 2 +- .../docs/interfaces/FluidPackageJsonFields.md | 11 ++- .../docs/interfaces/IFluidBuildDir.md | 20 +++++- .../docs/interfaces/IFluidRepo.md | 30 ++++---- .../docs/interfaces/IPackage.md | 41 ++++++----- .../docs/interfaces/IPackageManager.md | 17 ++++- .../docs/interfaces/IReleaseGroup.md | 24 ++++--- .../docs/interfaces/IWorkspace.md | 24 ++++--- .../docs/interfaces/Installable.md | 4 +- .../docs/interfaces/PackageDependency.md | 23 +++++-- .../docs/interfaces/ReleaseGroupDefinition.md | 12 ++-- .../docs/interfaces/Reloadable.md | 2 +- .../docs/interfaces/WorkspaceDefinition.md | 10 ++- .../type-aliases/AdditionalPackageProps.md | 4 +- .../docs/type-aliases/IFluidBuildDirEntry.md | 2 +- .../docs/type-aliases/PackageJson.md | 5 +- .../docs/type-aliases/PackageManagerName.md | 2 +- .../docs/type-aliases/PackageName.md | 2 +- .../docs/type-aliases/ReleaseGroupName.md | 2 +- .../docs/type-aliases/WorkspaceName.md | 2 +- .../build-infrastructure/src/config.ts | 28 ++++++-- .../build-infrastructure/src/index.ts | 11 +-- .../build-infrastructure/src/types.ts | 69 ++++++++++++++++--- 27 files changed, 261 insertions(+), 123 deletions(-) diff --git a/build-tools/packages/build-infrastructure/api-report/build-infrastructure.api.md b/build-tools/packages/build-infrastructure/api-report/build-infrastructure.api.md index 553e59a1b99f..9f564eeaa1c4 100644 --- a/build-tools/packages/build-infrastructure/api-report/build-infrastructure.api.md +++ b/build-tools/packages/build-infrastructure/api-report/build-infrastructure.api.md @@ -9,7 +9,7 @@ import type { PackageJson as PackageJson_2 } from 'type-fest'; import type { SetRequired } from 'type-fest'; import { SimpleGit } from 'simple-git'; -// @public (undocumented) +// @public export type AdditionalPackageProps = Record | undefined; // @public @@ -31,6 +31,8 @@ export function getFluidRepoLayout(searchPath: string, noCache?: boolean): { // @public @deprecated export interface IFluidBuildDir { directory: string; + // @deprecated + ignoredDirs?: string[]; } // @public @deprecated (undocumented) @@ -97,11 +99,8 @@ export interface IPackage extends Installab // @public export interface IPackageManager { - // (undocumented) installCommand(updateLockfile: boolean): string; - // (undocumented) readonly lockfileName: string; - // (undocumented) readonly name: PackageManagerName; } @@ -144,15 +143,12 @@ export class NotInGitRepository extends Error { // @public export interface PackageDependency { - // (undocumented) - depClass: "prod" | "dev" | "peer"; - // (undocumented) + depKind: "prod" | "dev" | "peer"; name: PackageName; - // (undocumented) version: string; } -// @public (undocumented) +// @public export type PackageJson = SetRequired; // @public @@ -161,7 +157,7 @@ export type PackageManagerName = "npm" | "pnpm" | "yarn"; // @public export type PackageName = Opaque; -// @public (undocumented) +// @public export interface ReleaseGroupDefinition { adoPipelineUrl?: string; exclude?: string[]; @@ -178,11 +174,9 @@ export interface Reloadable { reload(): void; } -// @public (undocumented) +// @public export interface WorkspaceDefinition { - // (undocumented) directory: string; - // (undocumented) releaseGroups: { [name: string]: ReleaseGroupDefinition; }; diff --git a/build-tools/packages/build-infrastructure/docs/README.md b/build-tools/packages/build-infrastructure/docs/README.md index 215ab6afe08e..52fec5d10147 100644 --- a/build-tools/packages/build-infrastructure/docs/README.md +++ b/build-tools/packages/build-infrastructure/docs/README.md @@ -241,15 +241,12 @@ That should be much easier now. - Inadequate testing of git-related APIs - can we mock git somehow? -build-infrastructure package comment. +This is the main entrypoint to the build-infrastructure API. -## Group - -API - -## Category - -API +The primary purpose of this package is to provide a common way to organize npm packages into groups called release +groups, and leverages workspaces functionality provided by package managers like npm, yarn, and pnpm to manage +interdependencies between packages across a Fluid repo. It then provides APIs to select, filter, and work with those +package groups. ## Classes diff --git a/build-tools/packages/build-infrastructure/docs/functions/getFluidRepoLayout.md b/build-tools/packages/build-infrastructure/docs/functions/getFluidRepoLayout.md index 5a51a6bd3dd5..010340a1eeaa 100644 --- a/build-tools/packages/build-infrastructure/docs/functions/getFluidRepoLayout.md +++ b/build-tools/packages/build-infrastructure/docs/functions/getFluidRepoLayout.md @@ -46,4 +46,4 @@ If a config is not found or if the config version is not supported. ## Defined in -[packages/build-infrastructure/src/config.ts:198](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L198) +[packages/build-infrastructure/src/config.ts:218](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L218) diff --git a/build-tools/packages/build-infrastructure/docs/functions/isIPackage.md b/build-tools/packages/build-infrastructure/docs/functions/isIPackage.md index e2219b075de6..a25a24496df6 100644 --- a/build-tools/packages/build-infrastructure/docs/functions/isIPackage.md +++ b/build-tools/packages/build-infrastructure/docs/functions/isIPackage.md @@ -22,4 +22,4 @@ A type guard that returns `true` if the item is an [IPackage](../interfaces/IPac ## Defined in -[packages/build-infrastructure/src/types.ts:379](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L379) +[packages/build-infrastructure/src/types.ts:430](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L430) diff --git a/build-tools/packages/build-infrastructure/docs/functions/isIReleaseGroup.md b/build-tools/packages/build-infrastructure/docs/functions/isIReleaseGroup.md index 87726a8e394f..f1e776c58cc7 100644 --- a/build-tools/packages/build-infrastructure/docs/functions/isIReleaseGroup.md +++ b/build-tools/packages/build-infrastructure/docs/functions/isIReleaseGroup.md @@ -22,4 +22,4 @@ A type guard that returns `true` if the checked item is an [IReleaseGroup](../in ## Defined in -[packages/build-infrastructure/src/types.ts:236](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L236) +[packages/build-infrastructure/src/types.ts:251](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L251) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/FluidPackageJsonFields.md b/build-tools/packages/build-infrastructure/docs/interfaces/FluidPackageJsonFields.md index 787bdef457a5..159e75235fc3 100644 --- a/build-tools/packages/build-infrastructure/docs/interfaces/FluidPackageJsonFields.md +++ b/build-tools/packages/build-infrastructure/docs/interfaces/FluidPackageJsonFields.md @@ -6,7 +6,8 @@ # Interface: FluidPackageJsonFields -A type representing fluid-build-specific config that may be in package.json. +Extra package.json fields used by pnpm. +See [https://pnpm.io/package_json](https://pnpm.io/package_json). ## Properties @@ -16,7 +17,8 @@ A type representing fluid-build-specific config that may be in package.json. optional pnpm: object; ``` -pnpm config +Configuration for pnpm. +See [https://pnpm.io/package_json](https://pnpm.io/package_json). #### overrides? @@ -24,6 +26,9 @@ pnpm config optional overrides: Record; ``` +Instruct pnpm to override any dependency in the dependency graph. +See [https://pnpm.io/package_json#pnpmoverrides](https://pnpm.io/package_json#pnpmoverrides) + #### Defined in -[packages/build-infrastructure/src/types.ts:18](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L18) +[packages/build-infrastructure/src/types.ts:20](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L20) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IFluidBuildDir.md b/build-tools/packages/build-infrastructure/docs/interfaces/IFluidBuildDir.md index ca2a173dcf2d..d90734dece7c 100644 --- a/build-tools/packages/build-infrastructure/docs/interfaces/IFluidBuildDir.md +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IFluidBuildDir.md @@ -24,4 +24,22 @@ The path to the package. For release groups this should be the path to the root #### Defined in -[packages/build-infrastructure/src/config.ts:110](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L110) +[packages/build-infrastructure/src/config.ts:128](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L128) + +*** + +### ~~ignoredDirs?~~ + +```ts +optional ignoredDirs: string[]; +``` + +An array of paths under `directory` that should be ignored. + +#### Deprecated + +This field is unused in all known configs and is ignored by the back-compat loading code. + +#### Defined in + +[packages/build-infrastructure/src/config.ts:135](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L135) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IFluidRepo.md b/build-tools/packages/build-infrastructure/docs/interfaces/IFluidRepo.md index e7ea6c6f8f0f..bd4931760e83 100644 --- a/build-tools/packages/build-infrastructure/docs/interfaces/IFluidRepo.md +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IFluidRepo.md @@ -20,6 +20,8 @@ See [IWorkspace](IWorkspace.md) and [IReleaseGroup](IReleaseGroup.md) for more d • **P** *extends* [`IPackage`](IPackage.md) = [`IPackage`](IPackage.md) +The type of [IPackage](IPackage.md) the repo uses. This can be any type that implements [IPackage](IPackage.md). + ## Properties ### configuration @@ -32,7 +34,7 @@ The layout configuration for the repo. #### Defined in -[packages/build-infrastructure/src/types.ts:67](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L67) +[packages/build-infrastructure/src/types.ts:82](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L82) *** @@ -46,7 +48,7 @@ A map of all packages in the Fluid repo. #### Defined in -[packages/build-infrastructure/src/types.ts:56](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L56) +[packages/build-infrastructure/src/types.ts:71](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L71) *** @@ -60,7 +62,7 @@ A map of all release groups in the Fluid repo. #### Defined in -[packages/build-infrastructure/src/types.ts:51](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L51) +[packages/build-infrastructure/src/types.ts:66](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L66) *** @@ -74,7 +76,7 @@ The absolute path to the root of the IFluidRepo. This is the path where the conf #### Defined in -[packages/build-infrastructure/src/types.ts:41](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L41) +[packages/build-infrastructure/src/types.ts:56](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L56) *** @@ -89,7 +91,7 @@ A partial URL to the upstream (remote) repo. This can be set to the name of the #### Defined in -[packages/build-infrastructure/src/types.ts:62](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L62) +[packages/build-infrastructure/src/types.ts:77](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L77) *** @@ -103,7 +105,7 @@ A map of all workspaces in the Fluid repo. #### Defined in -[packages/build-infrastructure/src/types.ts:46](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L46) +[packages/build-infrastructure/src/types.ts:61](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L61) ## Methods @@ -127,7 +129,7 @@ A [NotInGitRepository](../classes/NotInGitRepository.md) error if the path is no #### Defined in -[packages/build-infrastructure/src/types.ts:84](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L84) +[packages/build-infrastructure/src/types.ts:99](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L99) *** @@ -149,7 +151,7 @@ Returns the [IReleaseGroup](IReleaseGroup.md) associated with a package. #### Defined in -[packages/build-infrastructure/src/types.ts:89](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L89) +[packages/build-infrastructure/src/types.ts:104](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L104) *** @@ -171,7 +173,7 @@ Returns the [IWorkspace](IWorkspace.md) associated with a package. #### Defined in -[packages/build-infrastructure/src/types.ts:94](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L94) +[packages/build-infrastructure/src/types.ts:109](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L109) *** @@ -181,23 +183,23 @@ Returns the [IWorkspace](IWorkspace.md) associated with a package. relativeToRepo(p): string ``` -Transforms an absolute path to a path relative to the FluidRepo root. +Transforms an absolute path to a path relative to the IFluidRepo root. #### Parameters • **p**: `string` -The path to make relative to the FluidRepo root. +The path to make relative to the IFluidRepo root. #### Returns `string` -the relative path. +The path relative to the IFluidRepo root. #### Defined in -[packages/build-infrastructure/src/types.ts:75](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L75) +[packages/build-infrastructure/src/types.ts:90](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L90) *** @@ -217,4 +219,4 @@ reload(): void #### Defined in -[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) +[packages/build-infrastructure/src/types.ts:135](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L135) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IPackage.md b/build-tools/packages/build-infrastructure/docs/interfaces/IPackage.md index 648055178dbf..72f97bddcf9a 100644 --- a/build-tools/packages/build-infrastructure/docs/interfaces/IPackage.md +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IPackage.md @@ -17,6 +17,9 @@ when the package.json has custom keys/values. • **J** *extends* [`PackageJson`](../type-aliases/PackageJson.md) = [`PackageJson`](../type-aliases/PackageJson.md) +The package.json type to use. This type must extend the [PackageJson](../type-aliases/PackageJson.md) type defined in this +package. + ## Properties ### combinedDependencies @@ -30,7 +33,7 @@ dependencies. This is useful to iterate overall all dependencies of the package. #### Defined in -[packages/build-infrastructure/src/types.ts:371](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L371) +[packages/build-infrastructure/src/types.ts:422](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L422) *** @@ -45,7 +48,7 @@ for the package). #### Defined in -[packages/build-infrastructure/src/types.ts:302](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L302) +[packages/build-infrastructure/src/types.ts:353](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L353) *** @@ -60,7 +63,7 @@ does, it will only have one. #### Defined in -[packages/build-infrastructure/src/types.ts:349](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L349) +[packages/build-infrastructure/src/types.ts:400](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L400) *** @@ -74,7 +77,7 @@ Whether the package is a workspace root package or not. A workspace will only ha #### Defined in -[packages/build-infrastructure/src/types.ts:338](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L338) +[packages/build-infrastructure/src/types.ts:389](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L389) *** @@ -88,7 +91,7 @@ The name of the package #### Defined in -[packages/build-infrastructure/src/types.ts:290](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L290) +[packages/build-infrastructure/src/types.ts:341](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L341) *** @@ -103,7 +106,7 @@ the same color. #### Defined in -[packages/build-infrastructure/src/types.ts:296](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L296) +[packages/build-infrastructure/src/types.ts:347](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L347) *** @@ -117,7 +120,7 @@ The package.json contents of the package. #### Defined in -[packages/build-infrastructure/src/types.ts:307](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L307) +[packages/build-infrastructure/src/types.ts:358](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L358) *** @@ -131,7 +134,7 @@ The absolute path to the package.json file for this package. #### Defined in -[packages/build-infrastructure/src/types.ts:354](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L354) +[packages/build-infrastructure/src/types.ts:405](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L405) *** @@ -145,7 +148,7 @@ The package manager used to manage this package. #### Defined in -[packages/build-infrastructure/src/types.ts:317](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L317) +[packages/build-infrastructure/src/types.ts:368](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L368) *** @@ -160,7 +163,7 @@ returns a boolean value. If the package.json is missing the `private` field, thi #### Defined in -[packages/build-infrastructure/src/types.ts:328](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L328) +[packages/build-infrastructure/src/types.ts:379](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L379) *** @@ -174,7 +177,7 @@ The name of the release group that this package belongs to. #### Defined in -[packages/build-infrastructure/src/types.ts:343](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L343) +[packages/build-infrastructure/src/types.ts:394](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L394) *** @@ -188,7 +191,7 @@ The version of the package. This is the same as `packageJson.version`. #### Defined in -[packages/build-infrastructure/src/types.ts:322](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L322) +[packages/build-infrastructure/src/types.ts:373](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L373) *** @@ -202,7 +205,7 @@ The workspace that this package belongs to. #### Defined in -[packages/build-infrastructure/src/types.ts:333](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L333) +[packages/build-infrastructure/src/types.ts:384](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L384) ## Methods @@ -225,7 +228,7 @@ install. #### Defined in -[packages/build-infrastructure/src/types.ts:105](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L105) +[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) *** @@ -248,7 +251,7 @@ found. #### Defined in -[packages/build-infrastructure/src/types.ts:360](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L360) +[packages/build-infrastructure/src/types.ts:411](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L411) *** @@ -277,7 +280,7 @@ may cause the installation to fail. #### Defined in -[packages/build-infrastructure/src/types.ts:113](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L113) +[packages/build-infrastructure/src/types.ts:128](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L128) *** @@ -297,7 +300,7 @@ reload(): void #### Defined in -[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) +[packages/build-infrastructure/src/types.ts:135](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L135) *** @@ -315,7 +318,7 @@ Saves any changes to the packageJson property to the package.json file on disk. #### Defined in -[packages/build-infrastructure/src/types.ts:365](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L365) +[packages/build-infrastructure/src/types.ts:416](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L416) *** @@ -333,4 +336,4 @@ Returns a string representation of an object. #### Defined in -[packages/build-infrastructure/src/types.ts:372](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L372) +[packages/build-infrastructure/src/types.ts:423](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L423) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IPackageManager.md b/build-tools/packages/build-infrastructure/docs/interfaces/IPackageManager.md index 377ec95b016c..79edb9f3e8b9 100644 --- a/build-tools/packages/build-infrastructure/docs/interfaces/IPackageManager.md +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IPackageManager.md @@ -16,9 +16,11 @@ A package manager, such as "npm" or "pnpm". readonly lockfileName: string; ``` +The name of the lockfile used by the package manager. + #### Defined in -[packages/build-infrastructure/src/types.ts:263](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L263) +[packages/build-infrastructure/src/types.ts:285](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L285) *** @@ -28,9 +30,11 @@ readonly lockfileName: string; readonly name: PackageManagerName; ``` +The name of the package manager. + #### Defined in -[packages/build-infrastructure/src/types.ts:262](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L262) +[packages/build-infrastructure/src/types.ts:280](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L280) ## Methods @@ -40,14 +44,21 @@ readonly name: PackageManagerName; installCommand(updateLockfile): string ``` +Returns an install command that can be used to install dependencies using this package manager. + #### Parameters • **updateLockfile**: `boolean` +If `true`, then the returned command will include flags or arguments necessary to update +the lockfile during install. If `false`, such flags or arguments should be omitted. Note that the command will +_not_ include the package manager name istself. For example, the `npm` package manager will return the string +`"install"`, not `"npm install"`. + #### Returns `string` #### Defined in -[packages/build-infrastructure/src/types.ts:264](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L264) +[packages/build-infrastructure/src/types.ts:295](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L295) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IReleaseGroup.md b/build-tools/packages/build-infrastructure/docs/interfaces/IReleaseGroup.md index 047a5ded9638..51610a01db09 100644 --- a/build-tools/packages/build-infrastructure/docs/interfaces/IReleaseGroup.md +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IReleaseGroup.md @@ -29,7 +29,7 @@ An optional ADO pipeline URL for the CI pipeline that builds the release group. #### Defined in -[packages/build-infrastructure/src/types.ts:228](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L228) +[packages/build-infrastructure/src/types.ts:243](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L243) *** @@ -43,7 +43,7 @@ The name of the release group. All release groups must have unique names. #### Defined in -[packages/build-infrastructure/src/types.ts:196](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L196) +[packages/build-infrastructure/src/types.ts:211](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L211) *** @@ -57,7 +57,7 @@ An array of all packages in the release group. #### Defined in -[packages/build-infrastructure/src/types.ts:211](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L211) +[packages/build-infrastructure/src/types.ts:226](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L226) *** @@ -73,7 +73,7 @@ on the second. #### Defined in -[packages/build-infrastructure/src/types.ts:223](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L223) +[packages/build-infrastructure/src/types.ts:238](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L238) *** @@ -415,7 +415,8 @@ Indicate peer dependencies that are optional. optional pnpm: object; ``` -pnpm config +Configuration for pnpm. +See [https://pnpm.io/package_json](https://pnpm.io/package_json). ##### pnpm.overrides? @@ -423,6 +424,9 @@ pnpm config optional overrides: Record; ``` +Instruct pnpm to override any dependency in the dependency graph. +See [https://pnpm.io/package_json#pnpmoverrides](https://pnpm.io/package_json#pnpmoverrides) + ##### ~~preferGlobal?~~ ```ts @@ -539,7 +543,7 @@ Please note that the top-level `private` property of `package.json` **must** be #### Defined in -[packages/build-infrastructure/src/types.ts:206](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L206) +[packages/build-infrastructure/src/types.ts:221](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L221) *** @@ -553,7 +557,7 @@ The version of the release group. #### Defined in -[packages/build-infrastructure/src/types.ts:201](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L201) +[packages/build-infrastructure/src/types.ts:216](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L216) *** @@ -567,7 +571,7 @@ The workspace that the release group belongs to. #### Defined in -[packages/build-infrastructure/src/types.ts:216](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L216) +[packages/build-infrastructure/src/types.ts:231](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L231) ## Methods @@ -587,7 +591,7 @@ reload(): void #### Defined in -[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) +[packages/build-infrastructure/src/types.ts:135](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L135) *** @@ -605,4 +609,4 @@ Returns a string representation of an object. #### Defined in -[packages/build-infrastructure/src/types.ts:230](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L230) +[packages/build-infrastructure/src/types.ts:245](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L245) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/IWorkspace.md b/build-tools/packages/build-infrastructure/docs/interfaces/IWorkspace.md index 3f210f919757..86b43459298d 100644 --- a/build-tools/packages/build-infrastructure/docs/interfaces/IWorkspace.md +++ b/build-tools/packages/build-infrastructure/docs/interfaces/IWorkspace.md @@ -43,7 +43,7 @@ The root directory of the workspace. This directory will contain the workspace r #### Defined in -[packages/build-infrastructure/src/types.ts:159](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L159) +[packages/build-infrastructure/src/types.ts:174](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L174) *** @@ -57,7 +57,7 @@ The name of the workspace. #### Defined in -[packages/build-infrastructure/src/types.ts:154](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L154) +[packages/build-infrastructure/src/types.ts:169](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L169) *** @@ -72,7 +72,7 @@ constituent packages as well. #### Defined in -[packages/build-infrastructure/src/types.ts:175](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L175) +[packages/build-infrastructure/src/types.ts:190](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L190) *** @@ -86,7 +86,7 @@ A map of all the release groups in the workspace. #### Defined in -[packages/build-infrastructure/src/types.ts:169](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L169) +[packages/build-infrastructure/src/types.ts:184](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L184) *** @@ -428,7 +428,8 @@ Indicate peer dependencies that are optional. optional pnpm: object; ``` -pnpm config +Configuration for pnpm. +See [https://pnpm.io/package_json](https://pnpm.io/package_json). ##### pnpm.overrides? @@ -436,6 +437,9 @@ pnpm config optional overrides: Record; ``` +Instruct pnpm to override any dependency in the dependency graph. +See [https://pnpm.io/package_json#pnpmoverrides](https://pnpm.io/package_json#pnpmoverrides) + ##### ~~preferGlobal?~~ ```ts @@ -552,7 +556,7 @@ Please note that the top-level `private` property of `package.json` **must** be #### Defined in -[packages/build-infrastructure/src/types.ts:164](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L164) +[packages/build-infrastructure/src/types.ts:179](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L179) ## Methods @@ -575,7 +579,7 @@ install. #### Defined in -[packages/build-infrastructure/src/types.ts:105](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L105) +[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) *** @@ -604,7 +608,7 @@ may cause the installation to fail. #### Defined in -[packages/build-infrastructure/src/types.ts:113](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L113) +[packages/build-infrastructure/src/types.ts:128](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L128) *** @@ -624,7 +628,7 @@ reload(): void #### Defined in -[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) +[packages/build-infrastructure/src/types.ts:135](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L135) *** @@ -642,4 +646,4 @@ Returns a string representation of an object. #### Defined in -[packages/build-infrastructure/src/types.ts:176](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L176) +[packages/build-infrastructure/src/types.ts:191](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L191) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/Installable.md b/build-tools/packages/build-infrastructure/docs/interfaces/Installable.md index 0c8fcc83fe58..ef505acc6483 100644 --- a/build-tools/packages/build-infrastructure/docs/interfaces/Installable.md +++ b/build-tools/packages/build-infrastructure/docs/interfaces/Installable.md @@ -30,7 +30,7 @@ install. #### Defined in -[packages/build-infrastructure/src/types.ts:105](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L105) +[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) *** @@ -55,4 +55,4 @@ may cause the installation to fail. #### Defined in -[packages/build-infrastructure/src/types.ts:113](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L113) +[packages/build-infrastructure/src/types.ts:128](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L128) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/PackageDependency.md b/build-tools/packages/build-infrastructure/docs/interfaces/PackageDependency.md index 84dd47392595..5fb6e15063d8 100644 --- a/build-tools/packages/build-infrastructure/docs/interfaces/PackageDependency.md +++ b/build-tools/packages/build-infrastructure/docs/interfaces/PackageDependency.md @@ -6,19 +6,26 @@ # Interface: PackageDependency -Information about a package dependency. +Information about a package dependency. That is, en extry in the "dependencies", "devDependencies", or +"peerDependencies" fields in package.json. ## Properties -### depClass +### depKind ```ts -depClass: "prod" | "dev" | "peer"; +depKind: "prod" | "dev" | "peer"; ``` +The kind of dependency, based on the field that the dependency comes from. + +- prod corresponds to the dependencies field. +- dev corresponds to the devDependencies field. +- peer corresponds to the peerDependencies field. + #### Defined in -[packages/build-infrastructure/src/types.ts:272](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L272) +[packages/build-infrastructure/src/types.ts:320](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L320) *** @@ -28,9 +35,11 @@ depClass: "prod" | "dev" | "peer"; name: PackageName; ``` +The name of the dependency. + #### Defined in -[packages/build-infrastructure/src/types.ts:270](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L270) +[packages/build-infrastructure/src/types.ts:306](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L306) *** @@ -40,6 +49,8 @@ name: PackageName; version: string; ``` +The version or version range of the dependency. + #### Defined in -[packages/build-infrastructure/src/types.ts:271](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L271) +[packages/build-infrastructure/src/types.ts:311](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L311) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/ReleaseGroupDefinition.md b/build-tools/packages/build-infrastructure/docs/interfaces/ReleaseGroupDefinition.md index b04a3a62d7b7..738786f33d80 100644 --- a/build-tools/packages/build-infrastructure/docs/interfaces/ReleaseGroupDefinition.md +++ b/build-tools/packages/build-infrastructure/docs/interfaces/ReleaseGroupDefinition.md @@ -6,6 +6,8 @@ # Interface: ReleaseGroupDefinition +The definition of a release group ih configuration. + ## Properties ### adoPipelineUrl? @@ -18,7 +20,7 @@ A URL to the ADO CI pipeline that builds the release group. #### Defined in -[packages/build-infrastructure/src/config.ts:86](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L86) +[packages/build-infrastructure/src/config.ts:104](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L104) *** @@ -33,7 +35,7 @@ this can be used to exclude specific packages in a certain scope. #### Defined in -[packages/build-infrastructure/src/config.ts:69](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L69) +[packages/build-infrastructure/src/config.ts:87](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L87) *** @@ -46,9 +48,11 @@ include: string[]; An array of scopes or package names that should be included in the release group. Each package must belong to a single release group. +To include all packages, set this value to a single element: `["*"]`. + #### Defined in -[packages/build-infrastructure/src/config.ts:63](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L63) +[packages/build-infrastructure/src/config.ts:81](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L81) *** @@ -69,4 +73,4 @@ scripts. #### Defined in -[packages/build-infrastructure/src/config.ts:81](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L81) +[packages/build-infrastructure/src/config.ts:99](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L99) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/Reloadable.md b/build-tools/packages/build-infrastructure/docs/interfaces/Reloadable.md index b9fe91a7bbde..18cb1503d059 100644 --- a/build-tools/packages/build-infrastructure/docs/interfaces/Reloadable.md +++ b/build-tools/packages/build-infrastructure/docs/interfaces/Reloadable.md @@ -29,4 +29,4 @@ reload(): void #### Defined in -[packages/build-infrastructure/src/types.ts:120](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L120) +[packages/build-infrastructure/src/types.ts:135](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L135) diff --git a/build-tools/packages/build-infrastructure/docs/interfaces/WorkspaceDefinition.md b/build-tools/packages/build-infrastructure/docs/interfaces/WorkspaceDefinition.md index c598c08ad917..7fc96c5fdc7e 100644 --- a/build-tools/packages/build-infrastructure/docs/interfaces/WorkspaceDefinition.md +++ b/build-tools/packages/build-infrastructure/docs/interfaces/WorkspaceDefinition.md @@ -6,6 +6,8 @@ # Interface: WorkspaceDefinition +The definition of a workspace ih configuration. + ## Properties ### directory @@ -14,9 +16,11 @@ directory: string; ``` +The root directory of the workspace. This folder should contain a workspace config file (e.g. pnpm-workspace.yaml). + #### Defined in -[packages/build-infrastructure/src/config.ts:52](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L52) +[packages/build-infrastructure/src/config.ts:58](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L58) *** @@ -26,10 +30,12 @@ directory: string; releaseGroups: object; ``` +Definitions of the release groups within the workspace. + #### Index Signature \[`name`: `string`\]: [`ReleaseGroupDefinition`](ReleaseGroupDefinition.md) #### Defined in -[packages/build-infrastructure/src/config.ts:53](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L53) +[packages/build-infrastructure/src/config.ts:63](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L63) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/AdditionalPackageProps.md b/build-tools/packages/build-infrastructure/docs/type-aliases/AdditionalPackageProps.md index 238ba591cbe0..ee4eb529b2d5 100644 --- a/build-tools/packages/build-infrastructure/docs/type-aliases/AdditionalPackageProps.md +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/AdditionalPackageProps.md @@ -10,6 +10,8 @@ type AdditionalPackageProps: Record | undefined; ``` +Additional properties that can be added to an [IPackage](../interfaces/IPackage.md). + ## Defined in -[packages/build-infrastructure/src/types.ts:28](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L28) +[packages/build-infrastructure/src/types.ts:41](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L41) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/IFluidBuildDirEntry.md b/build-tools/packages/build-infrastructure/docs/type-aliases/IFluidBuildDirEntry.md index 94dcedf645ec..aef8370f6ac3 100644 --- a/build-tools/packages/build-infrastructure/docs/type-aliases/IFluidBuildDirEntry.md +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/IFluidBuildDirEntry.md @@ -16,4 +16,4 @@ Use repoLayout and associated types instead. ## Defined in -[packages/build-infrastructure/src/config.ts:99](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L99) +[packages/build-infrastructure/src/config.ts:117](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/config.ts#L117) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/PackageJson.md b/build-tools/packages/build-infrastructure/docs/type-aliases/PackageJson.md index 4233d5b0a31f..e7878967c47a 100644 --- a/build-tools/packages/build-infrastructure/docs/type-aliases/PackageJson.md +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/PackageJson.md @@ -10,6 +10,9 @@ type PackageJson: SetRequired; ``` +All known package.json fields including those that are specific to build-infrastructure. +The `name`, `scripts`, and `version` fields are required, unlike standard package.json. + ## Defined in -[packages/build-infrastructure/src/types.ts:23](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L23) +[packages/build-infrastructure/src/types.ts:33](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L33) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/PackageManagerName.md b/build-tools/packages/build-infrastructure/docs/type-aliases/PackageManagerName.md index edf9d6a3fd91..cbe5c9a2ad9b 100644 --- a/build-tools/packages/build-infrastructure/docs/type-aliases/PackageManagerName.md +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/PackageManagerName.md @@ -14,4 +14,4 @@ Known package managers supported by build-infrastructure. ## Defined in -[packages/build-infrastructure/src/types.ts:256](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L256) +[packages/build-infrastructure/src/types.ts:271](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L271) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/PackageName.md b/build-tools/packages/build-infrastructure/docs/type-aliases/PackageName.md index 0287be8e6fc2..5e689e7c98a2 100644 --- a/build-tools/packages/build-infrastructure/docs/type-aliases/PackageName.md +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/PackageName.md @@ -14,4 +14,4 @@ A tagged type representing package names. ## Defined in -[packages/build-infrastructure/src/types.ts:278](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L278) +[packages/build-infrastructure/src/types.ts:326](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L326) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/ReleaseGroupName.md b/build-tools/packages/build-infrastructure/docs/type-aliases/ReleaseGroupName.md index 15e23ca4e227..f826a048d20a 100644 --- a/build-tools/packages/build-infrastructure/docs/type-aliases/ReleaseGroupName.md +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/ReleaseGroupName.md @@ -14,4 +14,4 @@ A tagged type representing release group names. ## Defined in -[packages/build-infrastructure/src/types.ts:182](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L182) +[packages/build-infrastructure/src/types.ts:197](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L197) diff --git a/build-tools/packages/build-infrastructure/docs/type-aliases/WorkspaceName.md b/build-tools/packages/build-infrastructure/docs/type-aliases/WorkspaceName.md index d03d90550f1c..4a5f6c23ed7e 100644 --- a/build-tools/packages/build-infrastructure/docs/type-aliases/WorkspaceName.md +++ b/build-tools/packages/build-infrastructure/docs/type-aliases/WorkspaceName.md @@ -14,4 +14,4 @@ A tagged type representing workspace names. ## Defined in -[packages/build-infrastructure/src/types.ts:126](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L126) +[packages/build-infrastructure/src/types.ts:141](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-infrastructure/src/types.ts#L141) diff --git a/build-tools/packages/build-infrastructure/src/config.ts b/build-tools/packages/build-infrastructure/src/config.ts index d046fea3558b..840959945476 100644 --- a/build-tools/packages/build-infrastructure/src/config.ts +++ b/build-tools/packages/build-infrastructure/src/config.ts @@ -41,24 +41,42 @@ export interface IFluidRepoLayout { repoLayout?: { workspaces: { /** - * A mapping of workspace name to folder containing a workspace config file (e.g. pnpm-workspace.yaml) + * A mapping of workspace name to folder containing a workspace config file (e.g. pnpm-workspace.yaml). */ [name: string]: WorkspaceDefinition; }; }; } +/** + * The definition of a workspace ih configuration. + */ export interface WorkspaceDefinition { + /** + * The root directory of the workspace. This folder should contain a workspace config file (e.g. pnpm-workspace.yaml). + */ directory: string; + + /** + * Definitions of the release groups within the workspace. + */ releaseGroups: { + /** + * A mapping of release group name to a definition for the release group. + */ [name: string]: ReleaseGroupDefinition; }; } +/** + * The definition of a release group ih configuration. + */ export interface ReleaseGroupDefinition { /** * An array of scopes or package names that should be included in the release group. Each package must * belong to a single release group. + * + * To include all packages, set this value to a single element: `["*"]`. */ include: string[]; @@ -111,12 +129,14 @@ export interface IFluidBuildDir { /** * An array of paths under `directory` that should be ignored. + * + * @deprecated This field is unused in all known configs and is ignored by the back-compat loading code. */ - // ignoredDirs?: string[]; + ignoredDirs?: string[]; } /** - * Checks if a package matches a given release group definition. + * Checks if a package matches a given {@link ReleaseGroupDefinition}. * * @returns `true` if the package matches the release group definition; `false` otherwise. */ @@ -128,7 +148,7 @@ export function matchesReleaseGroupDefinition( let shouldInclude = false; if ( - // Special case: include with a single element, "*", should include all packages. + // Special case: an include value with a single element, "*", should include all packages. (include.length === 1 && include[0] === "*") || // If the package name matches an entry in the include list, it should be included include.includes(name) || diff --git a/build-tools/packages/build-infrastructure/src/index.ts b/build-tools/packages/build-infrastructure/src/index.ts index 8e5c39f02f29..f43ce7996414 100644 --- a/build-tools/packages/build-infrastructure/src/index.ts +++ b/build-tools/packages/build-infrastructure/src/index.ts @@ -4,11 +4,14 @@ */ /** - * build-infrastructure package comment. + * This is the main entrypoint to the build-infrastructure API. + * + * The primary purpose of this package is to provide a common way to organize npm packages into groups called release + * groups, and leverages workspaces functionality provided by package managers like npm, yarn, and pnpm to manage + * interdependencies between packages across a Fluid repo. It then provides APIs to select, filter, and work with those + * package groups. * * @module default entrypoint - * @group API - * @category API */ export { @@ -35,7 +38,7 @@ export type { ReleaseGroupName, Reloadable, WorkspaceName, - FluidPackageJsonFields, + PnpmPackageJsonFields as FluidPackageJsonFields, PackageDependency, IPackageManager, } from "./types.js"; diff --git a/build-tools/packages/build-infrastructure/src/types.ts b/build-tools/packages/build-infrastructure/src/types.ts index 10c24bc4bb71..5858a94b08cb 100644 --- a/build-tools/packages/build-infrastructure/src/types.ts +++ b/build-tools/packages/build-infrastructure/src/types.ts @@ -9,22 +9,35 @@ import type { Opaque, SetRequired, PackageJson as StandardPackageJson } from "ty import type { IFluidRepoLayout } from "./config.js"; /** - * A type representing fluid-build-specific config that may be in package.json. + * Extra package.json fields used by pnpm. + * See {@link https://pnpm.io/package_json}. */ -export interface FluidPackageJsonFields { +export interface PnpmPackageJsonFields { /** - * pnpm config + * Configuration for pnpm. + * See {@link https://pnpm.io/package_json}. */ pnpm?: { + /** + * Instruct pnpm to override any dependency in the dependency graph. + * See {@link https://pnpm.io/package_json#pnpmoverrides} + */ overrides?: Record; }; } +/** + * All known package.json fields including those that are specific to build-infrastructure. + * The `name`, `scripts`, and `version` fields are required, unlike standard package.json. + */ export type PackageJson = SetRequired< - StandardPackageJson & FluidPackageJsonFields, + StandardPackageJson & PnpmPackageJsonFields, "name" | "scripts" | "version" >; +/** + * Additional properties that can be added to an {@link IPackage}. + */ export type AdditionalPackageProps = Record | undefined; /** @@ -33,6 +46,8 @@ export type AdditionalPackageProps = Record | undefined; * represent ways to organize packages in the repo, but their purpose and function are different. * * See {@link IWorkspace} and {@link IReleaseGroup} for more details. + * + * @typeParam P - The type of {@link IPackage} the repo uses. This can be any type that implements {@link IPackage}. */ export interface IFluidRepo

extends Reloadable { /** @@ -67,10 +82,10 @@ export interface IFluidRepo

extends Reloadable { configuration: IFluidRepoLayout; /** - * Transforms an absolute path to a path relative to the FluidRepo root. + * Transforms an absolute path to a path relative to the IFluidRepo root. * - * @param p - The path to make relative to the FluidRepo root. - * @returns the relative path. + * @param p - The path to make relative to the IFluidRepo root. + * @returns The path relative to the IFluidRepo root. */ relativeToRepo(p: string): string; @@ -259,17 +274,50 @@ export type PackageManagerName = "npm" | "pnpm" | "yarn"; * A package manager, such as "npm" or "pnpm". */ export interface IPackageManager { + /** + * The name of the package manager. + */ readonly name: PackageManagerName; + + /** + * The name of the lockfile used by the package manager. + */ readonly lockfileName: string; + + /** + * Returns an install command that can be used to install dependencies using this package manager. + * + * @param updateLockfile - If `true`, then the returned command will include flags or arguments necessary to update + * the lockfile during install. If `false`, such flags or arguments should be omitted. Note that the command will + * _not_ include the package manager name istself. For example, the `npm` package manager will return the string + * `"install"`, not `"npm install"`. + */ installCommand(updateLockfile: boolean): string; } + /** - * Information about a package dependency. + * Information about a package dependency. That is, en extry in the "dependencies", "devDependencies", or + * "peerDependencies" fields in package.json. */ export interface PackageDependency { + /** + * The name of the dependency. + */ name: PackageName; + + /** + * The version or version range of the dependency. + */ version: string; - depClass: "prod" | "dev" | "peer"; + + /** + * The kind of dependency, based on the field that the dependency comes from. + * + * - prod corresponds to the dependencies field. + * - dev corresponds to the devDependencies field. + * - peer corresponds to the peerDependencies field. + */ + depKind: "prod" | "dev" | "peer"; } /** @@ -280,6 +328,9 @@ export type PackageName = Opaque; /** * A common type representing an npm package. A custom type can be used for the package.json schema, which is useful * when the package.json has custom keys/values. + * + * @typeParam J - The package.json type to use. This type must extend the {@link PackageJson} type defined in this + * package. */ export interface IPackage extends Installable, From 50509fa984d17e5e6cd4eeb3255e3d1873fdc464 Mon Sep 17 00:00:00 2001 From: Tyler Butler Date: Tue, 22 Oct 2024 10:21:14 -0700 Subject: [PATCH 3/5] deps --- build-tools/packages/build-infrastructure/package.json | 2 +- build-tools/pnpm-lock.yaml | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/build-tools/packages/build-infrastructure/package.json b/build-tools/packages/build-infrastructure/package.json index 0758e67d2bc8..ca0ea01b2b0b 100644 --- a/build-tools/packages/build-infrastructure/package.json +++ b/build-tools/packages/build-infrastructure/package.json @@ -95,7 +95,7 @@ "@types/node": "^18.18.6", "@types/semver": "^7.5.0", "c8": "^7.14.0", - "chai": "^4.3.7", + "chai": "^4.5.0", "chai-arrays": "^2.2.0", "concurrently": "^8.2.1", "copyfiles": "^2.4.1", diff --git a/build-tools/pnpm-lock.yaml b/build-tools/pnpm-lock.yaml index c9998d9141ac..27b80f81cd37 100644 --- a/build-tools/pnpm-lock.yaml +++ b/build-tools/pnpm-lock.yaml @@ -495,8 +495,8 @@ importers: specifier: ^7.14.0 version: 7.14.0 chai: - specifier: ^4.3.7 - version: 4.4.1 + specifier: ^4.5.0 + version: 4.5.0 chai-arrays: specifier: ^2.2.0 version: 2.2.0 @@ -5587,7 +5587,7 @@ packages: eslint: '*' eslint-plugin-import: '*' dependencies: - debug: 4.3.5(supports-color@8.1.1) + debug: 4.3.4(supports-color@8.1.1) enhanced-resolve: 5.15.0 eslint: 8.57.0 eslint-module-utils: 2.8.0(@typescript-eslint/parser@6.21.0)(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.6.1)(eslint@8.57.0) From 338fcdb78b027d9400cbfa2c335e69f4c450547b Mon Sep 17 00:00:00 2001 From: Tyler Butler Date: Tue, 22 Oct 2024 10:21:29 -0700 Subject: [PATCH 4/5] update test project --- .../src/test/data/testRepo/packages/shared/package.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/shared/package.json b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/shared/package.json index f154760b901f..f011813d0148 100644 --- a/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/shared/package.json +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/packages/shared/package.json @@ -11,7 +11,6 @@ "license": "MIT", "author": "Microsoft and contributors", "dependencies": { - "@group2/pkg-d": "1.0.0", - "@group3/pkg-g": "1.0.0" + "@group2/pkg-d": "1.0.0" } } From ea5fc632aac74c49b9f6dee86a033c6b41f8e76c Mon Sep 17 00:00:00 2001 From: Tyler Butler Date: Tue, 22 Oct 2024 10:42:01 -0700 Subject: [PATCH 5/5] lockfile --- .../build-infrastructure/src/test/data/testRepo/pnpm-lock.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/build-tools/packages/build-infrastructure/src/test/data/testRepo/pnpm-lock.yaml b/build-tools/packages/build-infrastructure/src/test/data/testRepo/pnpm-lock.yaml index 08d35f432ff5..3cbd1990b2f9 100644 --- a/build-tools/packages/build-infrastructure/src/test/data/testRepo/pnpm-lock.yaml +++ b/build-tools/packages/build-infrastructure/src/test/data/testRepo/pnpm-lock.yaml @@ -64,9 +64,6 @@ importers: '@group2/pkg-d': specifier: 1.0.0 version: link:../group2/pkg-d - '@group3/pkg-g': - specifier: 1.0.0 - version: link:../group3/pkg-g packages: