Improve API Digestion stability and include discrepancies visualization

README.md

@@ -6,23 +6,29 @@ The Visualizer is part of the [OpenSSF Scorecard Monitor](https://github.com/Uli
 
 ## Features
 
-**Scorecard Data Visualizer:** Display the OpenSSF Scorecard data in a visual format for easy understanding and analysis.
+### Scorecard Data Visualizer
+
+Display the OpenSSF Scorecard data in a visual format for easy understanding and analysis.
 
 <br>
     <div>
         <img src='.github/other/demo1.gif' alt="visualizer-in-action"/>
     </div>
 </br>
 
-**Scorecard Data Comparator:** Compare between two commits that reported Scorecard data. See how the scores changed and further details.
+### Scorecard Data Comparator
+
+Compare between two commits that reported Scorecard data. See how the scores changed and further details.
 
 <br>
     <div>
         <img src='.github/other/gif_comparator.gif' alt="comparator-in-action"/>
     </div>
 </br>
 
-**Scorecard Data Comparator Diff:** Makes easier the visualization of the differences in the Scorecard comparator reasoning and details.
+### Scorecard Data Comparator Diff
+
+Makes easier the visualization of the differences in the Scorecard comparator reasoning and details.
 
 <br>
     <div>
@@ -33,14 +39,25 @@ The Visualizer is part of the [OpenSSF Scorecard Monitor](https://github.com/Uli
     </div>
 </br>
 
-**Support to GitLab repositories:** The project provides support of visualization and diff comparation for GitLab projects. In the GitLab version, deps.dev and step security links are not included, as those platforms don't support GitLab projects yet. 
+### Support to GitLab repositories
+
+The project provides support of visualization and diff comparation for GitLab projects. In the GitLab version, deps.dev and step security links are not included, as those platforms don't support GitLab projects yet.
 
 <br>
     <div>
         <img src='.github/other/gitlab-support.png' alt="visualizer-for-gitlab-repos"/>
     </div>
 </br>
 
+### Discrepancies management
+
+The Scorecard API can provide discrepancies in the data while comparing between two commits due [technical reasons](https://github.com/ossf/scorecard/issues/3438). The visualizer provides a way to showcase the discrepancies found.
+
+<br>
+    <div>
+        <img src='.github/other/discrepancies.png' alt="discrepancies preview"/>
+    </div>
+</br>
 
 ## How to use it
 

src/components/ProjectCompartor.tsx → src/components/ProjectComparator.tsx

@@ -8,15 +8,20 @@ import CommonError from "./CommonError";
 import Collapsible from "./Collapsable";
 import Loading from "./Loading";
 import { ComparatorDiff } from "./ComparatorDiff";
-import { ScoreElement } from "../types";
+import { ScoreElement, ConsolidatedScoreElement } from "../types";
+import { getRefinedChecks } from "../utils/comparator/getRefinedChecks";
+import { areEqualElements } from "../utils/comparator/areEqualElements";
 
 import "../styles/ProjectDetails.css";
 
 function ProjectComparator() {
   const params = useParams();
   const { platform, org, repo, prevCommitHash, currentCommitHash } = params;
 
-  const [state, setState] = useState([]);
+  const [consolidatedData, setConsolidatedData] = useState<
+    ConsolidatedScoreElement[]
+  >([]);
+  const [discrepancies, setDiscrepancies] = useState<string[]>([]);
 
   const prevCommitQuery = useQuery({
     queryKey: ["prevCommit"],
@@ -49,45 +54,37 @@ function ProjectComparator() {
 
   useEffect(() => {
     const areEqualDetails = () => {
-      let consolidatedData;
-
       if (!previousData?.checks || !previousData?.score) {
         return;
       }
-      consolidatedData = currentData?.checks?.map(
-        (e1: ScoreElement, index: number) => {
-          if (
-            JSON.stringify(e1.details) !==
-              JSON.stringify(previousData?.checks[index].details) ||
-            JSON.stringify(e1.reason) !==
-              JSON.stringify(previousData?.checks[index].reason)
-          ) {
-            return {
-              areEqual: false,
-              name: previousData.checks[index].name,
-              details: e1.details,
-              reason: e1.reason,
-              score: e1.score,
-              short: e1.documentation.short,
-              url: e1.documentation.url,
-              prevDetails: previousData.checks[index].details,
-              prevReason: previousData.checks[index].reason,
-              prevScore: previousData.checks[index].score,
-            };
-          } else {
-            return {
-              areEqual: true,
-              name: e1.name,
-              details: e1.details,
-              reason: e1.reason,
-              score: e1.score,
-              short: e1.documentation.short,
-              url: e1.documentation.url,
-            };
-          }
-        },
+
+      const refinedChecks = getRefinedChecks(
+        previousData?.checks,
+        currentData?.checks,
       );
-      setState(consolidatedData);
+
+      const data = refinedChecks.common.map((name: string) => {
+        const previousElement = previousData?.checks?.filter(
+          (el: ScoreElement) => el.name === name,
+        )[0];
+        const currentElement = currentData?.checks?.filter(
+          (el: ScoreElement) => el.name === name,
+        )[0];
+        return {
+          areEqual: areEqualElements(currentElement, previousElement),
+          name: previousElement.name,
+          details: currentElement.details,
+          reason: currentElement.reason,
+          score: currentElement.score,
+          short: currentElement.documentation.short,
+          url: currentElement.documentation.url,
+          prevDetails: previousElement.details,
+          prevReason: previousElement.reason,
+          prevScore: previousElement.score,
+        };
+      });
+      setConsolidatedData(data);
+      setDiscrepancies(refinedChecks.discrepancies);
     };
     areEqualDetails();
   }, [currentData, previousData]);
@@ -139,9 +136,21 @@ function ProjectComparator() {
           {`(${currentData.scorecard.commit.substring(0, 8)})`}
         </a>
       </p>
+      {discrepancies.length > 0 && (
+        <span className="warning-message" data-testid="discrepancies">
+          {`Scorecard API missing: ${discrepancies.join(", ")} checks. See `}
+          <a
+            href="https://github.com/KoolTheba/openssf-scorecard-api-visualizer/tree/main#discrepancies-management"
+            target="_blank"
+            rel="noreferrer"
+          >
+            details
+          </a>
+        </span>
+      )}
       <hr />
-      {Array.isArray(state) &&
-        state.map((element: any) => (
+      {Array.isArray(consolidatedData) &&
+        consolidatedData.map((element: ConsolidatedScoreElement) => (
           <>
             <div key={element.name} className="card__wrapper">
               <div data-testid={element.name} className="heading__wrapper">
@@ -157,10 +166,8 @@ function ProjectComparator() {
                   See documentation
                 </a>
               </p>
-              {(element.prevDetails || element.prevReason) && (
-                <h4>Additional details / variations</h4>
-              )}
-              {element.prevReason && element.reason ? (
+              {!element.areEqual && <h4>Additional details / variations</h4>}
+              {!element.areEqual ? (
                 <p>
                   Reasoning:{" "}
                   <ComparatorDiff

src/components/ProjectDetails.tsx

@@ -64,7 +64,7 @@ function ProjectDetails() {
       </p>
       {platform === GITHUB && (
         <>
-           <p data-testid="deps-dev">
+          <p data-testid="deps-dev">
             Additional info at{" "}
             <a
               href={`https://deps.dev/project/github/${org}%2F${repo}`}

src/constants/checks.ts

@@ -0,0 +1,20 @@
+export const CHECKS_LIST_NAMES = [
+  "Binary-Artifacts",
+  "Branch-Protection",
+  "CI-Tests",
+  "CII-Best-Practices",
+  "Code-Review",
+  "Contributors",
+  "Dangerous-Workflow",
+  "Dependency-Update-Tool",
+  "Fuzzing",
+  "License",
+  "Maintained",
+  "Packaging",
+  "Pinned-Dependencies",
+  "SAST",
+  "Security-Policy",
+  "Signed-Releases",
+  "Token-Permissions",
+  "Vulnerabilities",
+];

src/constants/platforms.ts

@@ -1 +1 @@
-export const GITHUB = 'github.com'
+export const GITHUB = "github.com";

src/index.tsx

@@ -7,7 +7,7 @@ import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
 import NotFound from "./components/NotFound";
 import CommonError from "./components/CommonError";
 import ProjectDetails from "./components/ProjectDetails";
-import ProjectComparator from "./components/ProjectCompartor";
+import ProjectComparator from "./components/ProjectComparator";
 
 import reportWebVitals from "./reportWebVitals";
 import "./index.css";

src/styles/ProjectDetails.css

@@ -100,3 +100,15 @@ a:hover {
   flex-direction: row;
   align-items: center;
 }
+
+.warning-message {
+  width: auto;
+  padding: 10px;
+  color: black;
+  background-color: orange;
+  border-radius: 5px;
+  font-size: 1rem;
+  display: inline-block;
+  font-weight: 600;
+  line-height: 1.5rem;
+}

src/types/index.ts

@@ -8,3 +8,16 @@ export interface ScoreElement {
     url: string;
   };
 }
+
+export interface ConsolidatedScoreElement {
+  areEqual: boolean;
+  name: string;
+  details: string[];
+  reason: string;
+  score: number;
+  short: string;
+  url: string;
+  prevDetails: string[];
+  prevReason: string;
+  prevScore: number;
+}

src/utils/comparator/areEqualElements.test.js

@@ -0,0 +1,44 @@
+import { areEqualElements } from "./areEqualElements.tsx";
+
+const baseScoreElement = {
+  name: "foo",
+  score: 0,
+  reason: "sample reason",
+  details: ["sample detail"],
+  documentation: {
+    short: "documentation short",
+    url: "documentation url",
+  },
+};
+
+describe("util: areEqualElements", () => {
+  it("returns true if two elements are equal", () => {
+    expect(
+      areEqualElements(
+        { ...baseScoreElement, details: ["foo"], reason: "foo" },
+        { ...baseScoreElement, details: ["foo"], reason: "foo" },
+      ),
+    ).toBe(true);
+  });
+
+  it("returns false if two elements are not equal", () => {
+    expect(
+      areEqualElements(
+        { ...baseScoreElement, details: ["foo"], reason: "foo" },
+        { ...baseScoreElement, details: ["bar"], reason: "bar" },
+      ),
+    ).toBe(false);
+    expect(
+      areEqualElements(
+        { ...baseScoreElement, details: ["foo"], reason: "foo" },
+        { ...baseScoreElement, details: ["bar"], reason: "foo" },
+      ),
+    ).toBe(false);
+    expect(
+      areEqualElements(
+        { ...baseScoreElement, details: ["foo"], reason: "foo" },
+        { ...baseScoreElement, details: ["foo"], reason: "bar" },
+      ),
+    ).toBe(false);
+  });
+});

src/utils/comparator/areEqualElements.tsx

@@ -0,0 +1,10 @@
+import { ScoreElement } from "../../types";
+
+export const areEqualElements = (
+  currentElement: ScoreElement,
+  previousElement: ScoreElement,
+) =>
+  JSON.stringify(currentElement.details) ===
+    JSON.stringify(previousElement.details) &&
+  JSON.stringify(currentElement.reason) ===
+    JSON.stringify(previousElement.reason);

src/utils/comparator/getRefinedChecks.test.js

@@ -0,0 +1,42 @@
+import { getRefinedChecks } from "./getRefinedChecks.tsx";
+import { CHECKS_LIST_NAMES } from "../../constants/checks.ts";
+import sample1 from "../../../cypress/fixtures/2ac5e9889aba461f5a54d320973d2574980d206b.json";
+import sample2 from "../../../cypress/fixtures/077fd7d83d7d41695137c1af5b9be1d72250e69e.json";
+
+describe("util: getRefinedChecks", () => {
+  it("Should handle empty checks", () => {
+    expect(getRefinedChecks([], [])).toEqual({
+      common: [],
+      discrepancies: [],
+    });
+  });
+
+  it("Should handle an empty check", () => {
+    expect(getRefinedChecks(sample1.checks, [])).toEqual({
+      common: [],
+      discrepancies: CHECKS_LIST_NAMES,
+    });
+
+    expect(getRefinedChecks([], sample1.checks)).toEqual({
+      common: [],
+      discrepancies: CHECKS_LIST_NAMES,
+    });
+  });
+
+  it("Should generate a refined valid result", () => {
+    expect(getRefinedChecks(sample1.checks, sample2.checks)).toEqual({
+      common: CHECKS_LIST_NAMES,
+      discrepancies: [],
+    });
+  });
+
+  it("Should handle discrepancies and provide a valid result", () => {
+    const filteredList = sample1.checks.filter(
+      (item) => item.name !== "Binary-Artifacts",
+    );
+    expect(getRefinedChecks(filteredList, sample2.checks)).toEqual({
+      common: filteredList.map((item) => item.name),
+      discrepancies: ["Binary-Artifacts"],
+    });
+  });
+});