fix(markdown-magic): Add missing "EXAMPLE" scope support, and correctly differentiate unrecognized scopes from lack of scope (#21909)

Also updates test assets to use recognized scope.

tools/markdown-magic/src/utilities.cjs

@@ -95,18 +95,24 @@ function getPackageMetadata(packageJsonFilePath) {
  * Gets the appropriate special scope kind for the provided package name, if applicable.
  *
  * @param {string} packageName
- * @returns {"FRAMEWORK" | "EXPERIMENTAL" | "INTERNAL" | "PRIVATE" | "TOOLS" | undefined} A scope kind based on the package's scope (namespace).
- * Will be `undefined` if the package has no scope, or has an unrecognized scope.
+ * @returns {"" | "FRAMEWORK" | "EXAMPLE" | "EXPERIMENTAL" | "INTERNAL" | "PRIVATE" | "TOOLS" | undefined}
+ * A scope kind based on the package's scope (namespace).
+ * Will be an empty string if the package has no scope.
+ * Will be `undefined` if the package has an unrecognized scope.
  */
 const getScopeKindFromPackage = (packageName) => {
 	const packageScope = PackageName.getScope(packageName);
-	if (packageScope === `@fluidframework`) {
+	if (packageScope === "") {
+		return "";
+	} else if (packageScope === "@fluidframework") {
 		return "FRAMEWORK";
-	} else if (packageScope === `@fluid-experimental`) {
+	} else if (packageScope === "@fluid-example") {
+		return "EXAMPLE";
+	} else if (packageScope === "@fluid-experimental") {
 		return "EXPERIMENTAL";
-	} else if (packageScope === `@fluid-internal`) {
+	} else if (packageScope === "@fluid-internal") {
 		return "INTERNAL";
-	} else if (packageScope === `@fluid-private`) {
+	} else if (packageScope === "@fluid-private") {
 		return "PRIVATE";
 	} else if (packageScope === "@fluid-tools") {
 		return "TOOLS";
@@ -121,7 +127,7 @@ const getScopeKindFromPackage = (packageName) => {
  */
 const shouldLinkToApiDocs = (packageName) => {
 	const scope = getScopeKindFromPackage(packageName);
-	return scope === "FRAMEWORK" || scope === "EXPERIMENTAL" || scope === undefined;
+	return scope === "FRAMEWORK" || scope === "EXPERIMENTAL" || packageName === "fluid-framework";
 };
 
 /**

tools/markdown-magic/test/api-docs-link-section.md

@@ -3,7 +3,7 @@
 <!-- prettier-ignore-start -->
 <!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
 
-API documentation for **@test/test-package** is available at <https://fluidframework.com/docs/apis/test-package>.
+API documentation for **@fluidframework/test-package** is available at <https://fluidframework.com/docs/apis/test-package>.
 
 <!-- prettier-ignore-end -->
 
@@ -16,7 +16,7 @@ API documentation for **@test/test-package** is available at <https://fluidframe
 
 ## API Documentation
 
-API documentation for **@test/test-package** is available at <https://fluidframework.com/docs/apis/test-package>.
+API documentation for **@fluidframework/test-package** is available at <https://fluidframework.com/docs/apis/test-package>.
 
 <!-- prettier-ignore-end -->
 

tools/markdown-magic/test/example-package-readme.md

@@ -10,7 +10,7 @@ You can run this example using the following steps:
 1. Enable [corepack](https://nodejs.org/docs/latest-v16.x/api/corepack.html) by running `corepack enable`.
 1. Run `pnpm install` and `pnpm run build:fast --nolint` from the `FluidFramework` root directory.
     - For an even faster build, you can add the package name to the build command, like this:
-      `pnpm run build:fast --nolint @test/test-package`
+      `pnpm run build:fast --nolint @fluidframework/test-package`
 1. In a separate terminal, start a Tinylicious server by following the instructions in [Tinylicious](https://github.com/microsoft/FluidFramework/tree/main/server/routerlicious/packages/tinylicious).
 1. Run `pnpm start` from this directory and open <http://localhost:8080> in a web browser to see the app running.
 

tools/markdown-magic/test/library-package-readme-footer.md

@@ -5,7 +5,7 @@
 
 ## API Documentation
 
-API documentation for **@test/test-package** is available at <https://fluidframework.com/docs/apis/test-package>.
+API documentation for **@fluidframework/test-package** is available at <https://fluidframework.com/docs/apis/test-package>.
 
 ## Scripts
 

tools/markdown-magic/test/library-package-readme-header.md

@@ -21,7 +21,7 @@ If using any of Fluid Framework's unstable APIs (for example, its `beta` APIs),
 To get started, install the package by running the following command:
 
 ```bash
-npm i @test/test-package -D
+npm i @fluidframework/test-package -D
 ```
 
 ## Importing from this package
@@ -29,11 +29,11 @@ npm i @test/test-package -D
 This package leverages [package.json exports](https://nodejs.org/api/packages.html#exports) to separate its APIs by support level.
 For more information on the related support guarantees, see [API Support Levels](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels).
 
-To access the `public` ([SemVer](https://semver.org/)) APIs, import via `@test/test-package` like normal.
+To access the `public` ([SemVer](https://semver.org/)) APIs, import via `@fluidframework/test-package` like normal.
 
-To access the `alpha` APIs, import via `@test/test-package/alpha`.
+To access the `alpha` APIs, import via `@fluidframework/test-package/alpha`.
 
-To access the `legacy` APIs, import via `@test/test-package/legacy`.
+To access the `legacy` APIs, import via `@fluidframework/test-package/legacy`.
 
 <!-- prettier-ignore-end -->
 

tools/markdown-magic/test/package.json

@@ -1,5 +1,5 @@
 {
-	"name": "@test/test-package",
+	"name": "@fluidframework/test-package",
 	"version": "0.1.0",
 	"description": "This is a mock package.json for use in documentation generation tests.",
 	"homepage": "https://fluidframework.com",

tools/markdown-magic/test/readme-example-getting-started-section.md

@@ -10,7 +10,7 @@ You can run this example using the following steps:
 1. Enable [corepack](https://nodejs.org/docs/latest-v16.x/api/corepack.html) by running `corepack enable`.
 1. Run `pnpm install` and `pnpm run build:fast --nolint` from the `FluidFramework` root directory.
     - For an even faster build, you can add the package name to the build command, like this:
-      `pnpm run build:fast --nolint @test/test-package`
+      `pnpm run build:fast --nolint @fluidframework/test-package`
 1. In a separate terminal, start a Tinylicious server by following the instructions in [Tinylicious](https://github.com/microsoft/FluidFramework/tree/main/server/routerlicious/packages/tinylicious).
 1. Run `pnpm start` from this directory and open <http://localhost:8080> in a web browser to see the app running.
 
@@ -30,7 +30,7 @@ You can run this example using the following steps:
 1. Enable [corepack](https://nodejs.org/docs/latest-v16.x/api/corepack.html) by running `corepack enable`.
 1. Run `pnpm install` and `pnpm run build:fast --nolint` from the `FluidFramework` root directory.
     - For an even faster build, you can add the package name to the build command, like this:
-      `pnpm run build:fast --nolint @test/test-package`
+      `pnpm run build:fast --nolint @fluidframework/test-package`
 1. Run `pnpm start` from this directory and open <http://localhost:8080> in a web browser to see the app running.
 
 <!-- prettier-ignore-end -->

tools/markdown-magic/test/readme-installation-section.md

@@ -6,7 +6,7 @@
 To get started, install the package by running the following command:
 
 ```bash
-npm i @test/test-package
+npm i @fluidframework/test-package
 ```
 
 <!-- prettier-ignore-end -->
@@ -23,7 +23,7 @@ npm i @test/test-package
 To get started, install the package by running the following command:
 
 ```bash
-npm i @test/test-package -D
+npm i @fluidframework/test-package -D
 ```
 
 <!-- prettier-ignore-end -->