Deploy to production 🚀

.env.example

@@ -2,7 +2,7 @@ FRAMNA_DOCS_BASE_URL=http://localhost:3000
 FRAMNA_DOCS_TITLE=Framna Docs
 FRAMNA_DOCS_DESCRIPTION=Documentation for Framna's APIs
 FRAMNA_DOCS_HELP_URL=https://github.com/shapehq/framna-docs/wiki
-FRAMNA_DOCS_PROJECT_CONFIGURATION_FILENAME=.shape-docs.yml
+FRAMNA_DOCS_PROJECT_CONFIGURATION_FILENAME=.framna-docs.yml
 NEXTAUTH_URL=https://docs.example.com
 NEXTAUTH_SECRET=use [openssl rand -base64 32] to generate a 32 bytes value
 REDIS_URL=localhost
@@ -24,3 +24,4 @@ GITHUB_APP_ID=123456
 GITHUB_PRIVATE_KEY_BASE_64=base 64 encoded version of the private key - see README.md for more info
 ENCRYPTION_PUBLIC_KEY_BASE_64=base 64 encoded version of the public key
 ENCRYPTION_PRIVATE_KEY_BASE_64=base 64 encoded version of the private key
+NEXT_PUBLIC_ENABLE_DIFF_SIDEBAR=true

.github/workflows/check-changes-to-env.yml

@@ -1,7 +1,7 @@
 name: Check Changes to Env
 permissions:
   contents: read
-  pull-requests: read
+  pull-requests: write
   issues: write
 on:
   pull_request:

Dockerfile

@@ -1,5 +1,11 @@
 FROM node:24-alpine AS base
 
+FROM base AS oasdiff
+ARG OASDIFF_VERSION=2.10.0
+RUN apk add --no-cache curl tar ca-certificates
+RUN curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh \
+    | sh -s -- -b /usr/local/bin "v${OASDIFF_VERSION}"
+
 # Install dependencies only when needed
 FROM base AS deps
 # Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
@@ -46,6 +52,7 @@ RUN addgroup --system --gid 1001 nodejs
 RUN adduser --system --uid 1001 nextjs
 
 COPY --from=builder /app/public ./public
+COPY --from=oasdiff /usr/local/bin/oasdiff /usr/local/bin/oasdiff
 
 # Set the correct permission for prerender cache
 RUN mkdir .next

README.md

@@ -41,6 +41,17 @@ Please refer to the following articles in [the wiki](https://github.com/shapehq/
 - [Updating Documentation](https://github.com/shapehq/framna-docs/wiki/Updating-Documentation)
 - [Deploying Framna Docs](https://github.com/shapehq/framna-docs/wiki/Deploying-Framna-Docs)
 
+### Install the OpenAPI diff tool locally
+
+Framna Docs relies on the [`oasdiff`](https://github.com/oasdiff/oasdiff) CLI when comparing specifications.  
+
+On MacOS you can install with homebrew:
+
+```bash
+brew tap oasdiff/homebrew-oasdiff
+brew install oasdiff
+```
+
 ## 👨‍🔧 How does it work?
 
 Framna Docs uses [OpenAPI specifications](https://swagger.io) from GitHub repositories. Users log in with their GitHub account to access documentation for projects they have access to. A repository only needs an OpenAPI spec to be recognized by Framna Docs, but customization is possible with a .framna-docs.yml file. Here's an example:

__test__/diff/OasDiffCalculator.test.ts

@@ -0,0 +1,142 @@
+import { OasDiffCalculator } from "../../src/features/diff/data/OasDiffCalculator"
+import IGitHubClient from "../../src/common/github/IGitHubClient"
+
+const createMockGitHubClient = (
+    baseUrl: string,
+    headUrl: string,
+    mergeBaseSha = "abc123"
+): IGitHubClient => ({
+    async compareCommitsWithBasehead() {
+        return { mergeBaseSha }
+    },
+    async getRepositoryContent(request) {
+        if (request.ref === mergeBaseSha) {
+            return { downloadURL: baseUrl }
+        }
+        return { downloadURL: headUrl }
+    },
+    async graphql() {
+        return {}
+    },
+    async getPullRequestFiles() {
+        return []
+    },
+    async getPullRequestComments() {
+        return []
+    },
+    async addCommentToPullRequest() {},
+    async updatePullRequestComment() {}
+})
+
+test("It rejects non-GitHub URLs for base spec", async () => {
+    const mockGitHubClient = createMockGitHubClient(
+        "https://malicious-site.com/file.yaml",
+        "https://raw.githubusercontent.com/owner/repo/main/file.yaml"
+    )
+    const calculator = new OasDiffCalculator(mockGitHubClient)
+
+    await expect(
+        calculator.calculateDiff("owner", "repo", "path.yaml", "base", "head")
+    ).rejects.toThrow("Invalid URL for base spec")
+})
+
+test("It rejects invalid URLs", async () => {
+    const mockGitHubClient = createMockGitHubClient(
+        "not-a-valid-url",
+        "https://raw.githubusercontent.com/owner/repo/main/file.yaml"
+    )
+    const calculator = new OasDiffCalculator(mockGitHubClient)
+
+    await expect(
+        calculator.calculateDiff("owner", "repo", "path.yaml", "base", "head")
+    ).rejects.toThrow("Invalid URL for base spec")
+})
+
+test("It accepts raw.githubusercontent.com URLs", async () => {
+    const mockGitHubClient = createMockGitHubClient(
+        "https://raw.githubusercontent.com/owner/repo/main/file1.yaml",
+        "https://raw.githubusercontent.com/owner/repo/main/file2.yaml"
+    )
+    const calculator = new OasDiffCalculator(mockGitHubClient)
+
+    // This will fail when trying to execute oasdiff, but that's expected
+    // We're only testing that URL validation passes
+    await expect(
+        calculator.calculateDiff("owner", "repo", "path.yaml", "base", "head")
+    ).rejects.toThrow("Failed to execute OpenAPI diff tool")
+})
+
+test("It accepts github.com URLs", async () => {
+    const mockGitHubClient = createMockGitHubClient(
+        "https://github.com/owner/repo/raw/main/file1.yaml",
+        "https://github.com/owner/repo/raw/main/file2.yaml"
+    )
+    const calculator = new OasDiffCalculator(mockGitHubClient)
+
+    // This will fail when trying to execute oasdiff, but that's expected
+    // We're only testing that URL validation passes
+    await expect(
+        calculator.calculateDiff("owner", "repo", "path.yaml", "base", "head")
+    ).rejects.toThrow("Failed to execute OpenAPI diff tool")
+})
+
+test("It accepts api.github.com URLs", async () => {
+    const mockGitHubClient = createMockGitHubClient(
+        "https://api.github.com/repos/owner/repo/contents/file1.yaml",
+        "https://api.github.com/repos/owner/repo/contents/file2.yaml"
+    )
+    const calculator = new OasDiffCalculator(mockGitHubClient)
+
+    // This will fail when trying to execute oasdiff, but that's expected
+    // We're only testing that URL validation passes
+    await expect(
+        calculator.calculateDiff("owner", "repo", "path.yaml", "base", "head")
+    ).rejects.toThrow("Failed to execute OpenAPI diff tool")
+})
+
+test("It rejects URLs with GitHub-like subdomains but different domains", async () => {
+    const mockGitHubClient = createMockGitHubClient(
+        "https://raw.githubusercontent.com.evil.com/file.yaml",
+        "https://raw.githubusercontent.com/owner/repo/main/file.yaml"
+    )
+    const calculator = new OasDiffCalculator(mockGitHubClient)
+
+    await expect(
+        calculator.calculateDiff("owner", "repo", "path.yaml", "base", "head")
+    ).rejects.toThrow("Invalid URL for base spec")
+})
+
+test("It validates both base and head URLs", async () => {
+    const mockGitHubClient = createMockGitHubClient(
+        "https://raw.githubusercontent.com/owner/repo/main/file1.yaml",
+        "https://malicious-site.com/file.yaml"
+    )
+    const calculator = new OasDiffCalculator(mockGitHubClient)
+
+    await expect(
+        calculator.calculateDiff("owner", "repo", "path.yaml", "base", "head")
+    ).rejects.toThrow("Invalid URL for head spec")
+})
+
+test("It returns empty changes when comparing same refs", async () => {
+    const mockGitHubClient = createMockGitHubClient(
+        "https://raw.githubusercontent.com/owner/repo/main/file1.yaml",
+        "https://raw.githubusercontent.com/owner/repo/main/file2.yaml",
+        "abc123"
+    )
+    const calculator = new OasDiffCalculator(mockGitHubClient)
+
+    const result = await calculator.calculateDiff(
+        "owner",
+        "repo",
+        "path.yaml",
+        "abc123",
+        "abc123"
+    )
+
+    expect(result).toEqual({
+        from: "abc123",
+        to: "abc123",
+        changes: []
+    })
+})

__test__/projects/GitHubProjectDataSource.test.ts

@@ -845,11 +845,13 @@ test("It adds remote versions from the project configuration", async () => {
       id: "huey",
       name: "Huey",
       url: `/api/remotes/${base64RemoteConfigEncoder.encode({ url: "https://example.com/huey.yml" })}`,
+      urlHash: "89ba381286214eec",
       isDefault: false
     }, {
       id: "dewey",
       name: "Dewey",
       url: `/api/remotes/${base64RemoteConfigEncoder.encode({ url: "https://example.com/dewey.yml" })}`,
+      urlHash: "8f810fff152505f6",
       isDefault: false
     }]
   }, {
@@ -860,6 +862,7 @@ test("It adds remote versions from the project configuration", async () => {
       id: "louie",
       name: "Louie",
       url: `/api/remotes/${base64RemoteConfigEncoder.encode({ url: "https://example.com/louie.yml" })}`,
+      urlHash: "b83ebf43ceede6bc",
       isDefault: false
     }]
   }])
@@ -925,6 +928,7 @@ test("It modifies ID of remote version if the ID already exists", async () => {
       id: "baz",
       name: "Baz",
       url: `/api/remotes/${base64RemoteConfigEncoder.encode({ url: "https://example.com/baz.yml" })}`,
+      urlHash: "25cb42ff63570cb5",
       isDefault: false
     }]
   }, {
@@ -935,6 +939,7 @@ test("It modifies ID of remote version if the ID already exists", async () => {
       id: "hello",
       name: "Hello",
       url: `/api/remotes/${base64RemoteConfigEncoder.encode({ url: "https://example.com/hello.yml" })}`,
+      urlHash: "d078bd689699d1f0",
       isDefault: false
     }]
   }])
@@ -979,6 +984,7 @@ test("It lets users specify the ID of a remote version", async () => {
       id: "baz",
       name: "Baz",
       url: `/api/remotes/${base64RemoteConfigEncoder.encode({ url: "https://example.com/baz.yml" })}`,
+      urlHash: "25cb42ff63570cb5",
       isDefault: false
     }]
   }])
@@ -1023,6 +1029,7 @@ test("It lets users specify the ID of a remote specification", async () => {
       id: "some-spec",
       name: "Baz",
       url: `/api/remotes/${base64RemoteConfigEncoder.encode({ url: "https://example.com/baz.yml" })}`,
+      urlHash: "25cb42ff63570cb5",
       isDefault: false
     }]
   }])