Diff sidebar (#607)

Add diff sidebar

Shows changes to OpenAPI spec between two branches using the oasdiff tool.

---------

Co-authored-by: Ulrik Andersen <ulrik@shape.dk>

Author: oscarlund121

.env.example

@@ -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: []
+    })
+})