Improve API Digestion stability and include discrepancies visualization

README.md

@@ -33,14 +33,21 @@ 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,21 @@ 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";
+import "../styles/ProjectComparator.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 +55,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 +137,17 @@ function ProjectComparator() {
           {`(${currentData.scorecard.commit.substring(0, 8)})`}
         </a>
       </p>
+      {discrepancies.length > 0 && (
+        <span
+          className="warning-message"
+          data-testid="discrepancies"
+        >{`The report doesn't display certain checks (such as ${discrepancies.join(
+          ", ",
+        )}) because they haven't been included in the analysis of both commits.`}</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 +163,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/ProjectComparator.css

@@ -0,0 +1,16 @@
+.warning-message {
+  width: auto;
+  padding: 10px;
+  color: white;
+  background-color: #dc3545;
+  /*border: 1px solid orange;*/
+  border-radius: 5px;
+  font-size: 1rem;
+  display: inline-block;
+  font-weight: 600;
+}
+
+.warning-message::before {
+  content: "\1F6A8";
+  margin-right: 4px;
+}

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"],
+    });
+  });
+});

src/utils/comparator/getRefinedChecks.tsx

@@ -0,0 +1,37 @@
+import { ScoreElement } from "../../types";
+import { CHECKS_LIST_NAMES } from "../../constants/checks";
+
+export const getRefinedChecks = (
+  from: ScoreElement[] = [],
+  to: ScoreElement[] = [],
+) => {
+  const haveMaxChecksNumber =
+    from.length === CHECKS_LIST_NAMES.length &&
+    to.length === CHECKS_LIST_NAMES.length;
+
+  if (haveMaxChecksNumber) {
+    return {
+      common: CHECKS_LIST_NAMES,
+      discrepancies: [],
+    };
+  }
+
+  const fromNames = from.map((el: ScoreElement) => el.name);
+  const toNames = to.map((el: ScoreElement) => el.name);
+  const allNames = new Set([...fromNames, ...toNames]);
+  const common = [];
+  const discrepancies = [];
+
+  for (const name of allNames) {
+    if (fromNames.includes(name) && toNames.includes(name)) {
+      common.push(name);
+    } else {
+      discrepancies.push(name);
+    }
+  }
+
+  return {
+    common: common.sort(),
+    discrepancies: discrepancies.sort(),
+  };
+};