(followup): add tests for playground validation messages

packages/cli/project-loader/src/index.ts

@@ -1,2 +1,2 @@
-export { loadApis, loadProject } from "./loadProject";
+export { loadApis, loadProject, loadProjectFromDirectory } from "./loadProject";
 export { type Project } from "./Project";

packages/cli/project-loader/src/loadProject.ts

@@ -2,10 +2,10 @@ import {
     APIS_DIRECTORY,
     ASYNCAPI_DIRECTORY,
     DEFINITION_DIRECTORY,
-    fernConfigJson,
     FERN_DIRECTORY,
-    generatorsYml,
+    fernConfigJson,
     GENERATORS_CONFIGURATION_FILENAME,
+    generatorsYml,
     getFernDirectory,
     OPENAPI_DIRECTORY
 } from "@fern-api/configuration";
@@ -35,33 +35,48 @@ export declare namespace loadProject {
         nameOverride?: string;
         sdkLanguage?: generatorsYml.GenerationLanguage;
     }
+
+    export interface LoadProjectFromDirectoryArgs extends Args {
+        absolutePathToFernDirectory: AbsoluteFilePath;
+    }
 }
 
-export async function loadProject({
-    cliName,
-    cliVersion,
-    commandLineApiWorkspace,
-    defaultToAllApiWorkspaces,
-    context,
-    nameOverride
-}: loadProject.Args): Promise<Project> {
+export async function loadProject({ context, nameOverride, ...args }: loadProject.Args): Promise<Project> {
     const fernDirectory = await getFernDirectory(nameOverride);
     if (fernDirectory == null) {
         return context.failAndThrow(`Directory "${nameOverride ?? FERN_DIRECTORY}" not found.`);
     }
 
+    return await loadProjectFromDirectory({
+        absolutePathToFernDirectory: fernDirectory,
+        context,
+        nameOverride,
+        ...args
+    });
+}
+
+export async function loadProjectFromDirectory({
+    absolutePathToFernDirectory,
+    cliName,
+    cliVersion,
+    commandLineApiWorkspace,
+    defaultToAllApiWorkspaces,
+    context
+}: loadProject.LoadProjectFromDirectoryArgs): Promise<Project> {
     let apiWorkspaces: APIWorkspace[] = [];
 
     if (
-        (await doesPathExist(join(fernDirectory, RelativeFilePath.of(APIS_DIRECTORY)))) ||
-        doesPathExist(join(fernDirectory, RelativeFilePath.of(DEFINITION_DIRECTORY))) ||
-        doesPathExist(join(fernDirectory, RelativeFilePath.of(GENERATORS_CONFIGURATION_FILENAME))) ||
-        doesPathExist(join(fernDirectory, RelativeFilePath.of(OPENAPI_DIRECTORY))) ||
-        doesPathExist(join(fernDirectory, RelativeFilePath.of(ASYNCAPI_DIRECTORY)))
+        (await doesPathExist(join(absolutePathToFernDirectory, RelativeFilePath.of(APIS_DIRECTORY)))) ||
+        (await doesPathExist(join(absolutePathToFernDirectory, RelativeFilePath.of(DEFINITION_DIRECTORY)))) ||
+        (await doesPathExist(
+            join(absolutePathToFernDirectory, RelativeFilePath.of(GENERATORS_CONFIGURATION_FILENAME))
+        )) ||
+        (await doesPathExist(join(absolutePathToFernDirectory, RelativeFilePath.of(OPENAPI_DIRECTORY)))) ||
+        (await doesPathExist(join(absolutePathToFernDirectory, RelativeFilePath.of(ASYNCAPI_DIRECTORY))))
     ) {
         apiWorkspaces = await loadApis({
             cliName,
-            fernDirectory,
+            fernDirectory: absolutePathToFernDirectory,
             cliVersion,
             context,
             commandLineApiWorkspace,
@@ -70,9 +85,9 @@ export async function loadProject({
     }
 
     return {
-        config: await fernConfigJson.loadProjectConfig({ directory: fernDirectory, context }),
+        config: await fernConfigJson.loadProjectConfig({ directory: absolutePathToFernDirectory, context }),
         apiWorkspaces,
-        docsWorkspaces: await loadDocsWorkspace({ fernDirectory, context }),
+        docsWorkspaces: await loadDocsWorkspace({ fernDirectory: absolutePathToFernDirectory, context }),
         loadAPIWorkspace: (name: string | undefined): APIWorkspace | undefined => {
             if (name == null) {
                 return apiWorkspaces[0];

packages/cli/yaml/docs-validator/package.json

@@ -32,6 +32,7 @@
     "@fern-api/docs-markdown-utils": "workspace:*",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/logger": "workspace:*",
+    "@fern-api/project-loader": "workspace:*",
     "@fern-api/task-context": "workspace:*",
     "@fern-api/workspace-loader": "workspace:*",
     "@fern-api/yaml-schema": "workspace:*",
@@ -43,6 +44,7 @@
     "rehype-katex": "^7.0.0",
     "remark-gfm": "^4.0.0",
     "remark-math": "^6.0.0",
+    "strip-ansi": "^7.1.0",
     "tinycolor2": "^1.6.0",
     "zod": "^3.22.3"
   },

packages/cli/yaml/docs-validator/src/rules/playground-environments-exist/__test__/__snapshots__/playground-environments-exist.test.ts.snap

@@ -0,0 +1,31 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`playground-environments-exist > no environments in api definition 1`] = `
+[
+  {
+    "message": "The API does not contain the Staging environment. ",
+    "nodePath": [
+      "navigation",
+      "0",
+      "api",
+    ],
+    "relativeFilepath": "docs.yml",
+    "severity": "error",
+  },
+]
+`;
+
+exports[`playground-environments-exist > non existent environment specified 1`] = `
+[
+  {
+    "message": "The API does not contain the Staging environment. Existing enviroments include Production, Dev.",
+    "nodePath": [
+      "navigation",
+      "0",
+      "api",
+    ],
+    "relativeFilepath": "docs.yml",
+    "severity": "error",
+  },
+]
+`;

packages/cli/yaml/docs-validator/src/rules/playground-environments-exist/__test__/fixtures/no-environments-in-api/fern/definition/api.yml

@@ -0,0 +1,3 @@
+name: api
+error-discrimination:
+  strategy: status-code

packages/cli/yaml/docs-validator/src/rules/playground-environments-exist/__test__/fixtures/no-environments-in-api/fern/definition/imdb.yml

@@ -0,0 +1,60 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json
+
+service:
+  auth: false
+  base-path: /movies
+  endpoints:
+    createMovie:
+      docs: Add a movie to the database
+      method: POST
+      path: /create-movie
+      request: CreateMovieRequest
+      response: MovieId
+
+    getMovie:
+      docs: Retrieve a movie from the database based on the ID
+      method: GET
+      path: /{id}
+      path-parameters:
+        id: MovieId
+      response: Movie
+      errors:
+        - MovieDoesNotExistError
+      examples:
+        # Success response
+        - path-parameters:
+            id: tt0111161
+          response:
+            body:
+              id: tt0111161
+              title: The Shawshank Redemption
+              rating: 9.3
+        # Error response
+        - path-parameters:
+            id: tt1234
+          response:
+            error: MovieDoesNotExistError
+            body: tt1234
+
+types:
+  MovieId:
+    type: string
+    docs: The unique identifier for a Movie in the database
+
+  Movie:
+    properties:
+      id: MovieId
+      title: string
+      rating:
+        type: double
+        docs: The rating scale out of ten stars
+
+  CreateMovieRequest:
+    properties:
+      title: string
+      rating: double
+
+errors:
+  MovieDoesNotExistError:
+    status-code: 404
+    type: MovieId

packages/cli/yaml/docs-validator/src/rules/playground-environments-exist/__test__/fixtures/no-environments-in-api/fern/docs.yml

@@ -0,0 +1,11 @@
+instances:
+  - url: https://fern.docs.buildwithfern.com
+title: Fern | Documentation
+navigation:
+  - api: API Reference
+    playground: 
+      environments: 
+        - Staging
+colors:
+  accentPrimary: '#ffffff'
+  background: '#000000'

packages/cli/yaml/docs-validator/src/rules/playground-environments-exist/__test__/fixtures/no-environments-in-api/fern/fern.config.json

@@ -0,0 +1,4 @@
+{
+    "organization": "fern",
+    "version": "0.37.16"
+}

packages/cli/yaml/docs-validator/src/rules/playground-environments-exist/__test__/fixtures/no-environments-in-api/fern/generators.yml

@@ -0,0 +1,9 @@
+default-group: local
+groups:
+  local:
+    generators:
+      - name: fernapi/fern-typescript-node-sdk
+        version: 0.9.5
+        output:
+          location: local-file-system
+          path: ../sdks/typescript

packages/cli/yaml/docs-validator/src/rules/playground-environments-exist/__test__/fixtures/wrong-environments-in-docs/fern/definition/api.yml

@@ -0,0 +1,6 @@
+name: api
+environments: 
+  Production: prod.com
+  Dev: dev.com
+error-discrimination:
+  strategy: status-code

packages/cli/yaml/docs-validator/src/rules/playground-environments-exist/__test__/fixtures/wrong-environments-in-docs/fern/definition/imdb.yml

@@ -0,0 +1,60 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json
+
+service:
+  auth: false
+  base-path: /movies
+  endpoints:
+    createMovie:
+      docs: Add a movie to the database
+      method: POST
+      path: /create-movie
+      request: CreateMovieRequest
+      response: MovieId
+
+    getMovie:
+      docs: Retrieve a movie from the database based on the ID
+      method: GET
+      path: /{id}
+      path-parameters:
+        id: MovieId
+      response: Movie
+      errors:
+        - MovieDoesNotExistError
+      examples:
+        # Success response
+        - path-parameters:
+            id: tt0111161
+          response:
+            body:
+              id: tt0111161
+              title: The Shawshank Redemption
+              rating: 9.3
+        # Error response
+        - path-parameters:
+            id: tt1234
+          response:
+            error: MovieDoesNotExistError
+            body: tt1234
+
+types:
+  MovieId:
+    type: string
+    docs: The unique identifier for a Movie in the database
+
+  Movie:
+    properties:
+      id: MovieId
+      title: string
+      rating:
+        type: double
+        docs: The rating scale out of ten stars
+
+  CreateMovieRequest:
+    properties:
+      title: string
+      rating: double
+
+errors:
+  MovieDoesNotExistError:
+    status-code: 404
+    type: MovieId

packages/cli/yaml/docs-validator/src/rules/playground-environments-exist/__test__/fixtures/wrong-environments-in-docs/fern/docs.yml

@@ -0,0 +1,11 @@
+instances:
+  - url: https://fern.docs.buildwithfern.com
+title: Fern | Documentation
+navigation:
+  - api: API Reference
+    playground: 
+      environments: 
+        - Staging
+colors:
+  accentPrimary: '#ffffff'
+  background: '#000000'

packages/cli/yaml/docs-validator/src/rules/playground-environments-exist/__test__/fixtures/wrong-environments-in-docs/fern/fern.config.json

@@ -0,0 +1,4 @@
+{
+    "organization": "fern",
+    "version": "0.37.16"
+}

packages/cli/yaml/docs-validator/src/rules/playground-environments-exist/__test__/fixtures/wrong-environments-in-docs/fern/generators.yml

@@ -0,0 +1,9 @@
+default-group: local
+groups:
+  local:
+    generators:
+      - name: fernapi/fern-typescript-node-sdk
+        version: 0.9.5
+        output:
+          location: local-file-system
+          path: ../sdks/typescript

packages/cli/yaml/docs-validator/src/rules/playground-environments-exist/__test__/playground-environments-exist.test.ts

@@ -0,0 +1,33 @@
+import { AbsoluteFilePath, join, RelativeFilePath } from "@fern-api/fs-utils";
+import { getViolationsForRule } from "../../../testing-utils/getViolationsForRule";
+import { PlaygroundEnvironmentsExistRule } from "../playground-environments-exist";
+
+describe("playground-environments-exist", () => {
+    it("no environments in api definition", async () => {
+        const violations = await getViolationsForRule({
+            rule: PlaygroundEnvironmentsExistRule,
+            absolutePathToFernDirectory: join(
+                AbsoluteFilePath.of(__dirname),
+                RelativeFilePath.of("fixtures"),
+                RelativeFilePath.of("no-environments-in-api"),
+                RelativeFilePath.of("fern")
+            )
+        });
+
+        expect(violations).toMatchSnapshot();
+    });
+
+    it("non existent environment specified", async () => {
+        const violations = await getViolationsForRule({
+            rule: PlaygroundEnvironmentsExistRule,
+            absolutePathToFernDirectory: join(
+                AbsoluteFilePath.of(__dirname),
+                RelativeFilePath.of("fixtures"),
+                RelativeFilePath.of("wrong-environments-in-docs"),
+                RelativeFilePath.of("fern")
+            )
+        });
+
+        expect(violations).toMatchSnapshot();
+    });
+});