Describe utils in with JS Doc

JS Doc is a widely used method of documenting Javascript.
It is widely supported by IDEs and runs in IDEs so doesn't require an
application depedencies - it's on the developer to keep their env up to
date.
It gives many of the benefits of Typescript without the learning curve
and the build step. It can (and should) be added optionally to improve
documentation and developer experience but it is optional won't effect
the run time code.

utils.js

@@ -1,4 +1,22 @@
 import { readFile } from "fs/promises";
+
+/**
+ * @typedef {Object} PersistedData
+ * @property {StoredRepo[]} repos - An array of repos.
+ * @property {number} totalRepos - The total number of repos.
+ * @property {string} org - The name of the Github organisation the repos belong to.
+ */
+
+/**
+ * @typedef {PersistedData} RepoData
+ * @property {UiRepo[]} repos - An array of repos.
+ */
+
+/**
+ * Maps the persisted repo data from storage to a format suitable for the UI
+ * @param {PersistedData} persistedData
+ * @returns {RepoData}
+ */
 export const mapRepoFromStorageToUi = (persistedData) => {
   const mappedRepos = persistedData.repos.map((repo) => {
     const newDate = new Date(repo.updatedAt).toLocaleDateString();
@@ -13,13 +31,57 @@ export const mapRepoFromStorageToUi = (persistedData) => {
   return { ...persistedData, repos: mappedRepos, totalRepos };
 };
 
+/**
+ * Reads the persisted repo data from a JSON file
+ * @param {string} filePath - The path to the file to read from
+ * @returns {PersistedData}
+ */
 export const getReposFromJson = async (filePath) => {
   const reposJson = await readFile(filePath, { encoding: "utf-8" });
   const persistedData = JSON.parse(reposJson);
 
   return persistedData;
 };
 
+/**
+ * @typedef {Object} ApiRepo
+ * @property {string} name - The name of the repo Eg "dalmation".
+ * @property {string} description - A brief description of the repo.
+ * @property {string} html_url - The URL to the repo on GitHub for humans.
+ * @property {string} pulls_url - The API url to get more info on pull requests for this repo.
+ * @property {string} issues_url - The API url to get more info on issues for this repo.
+ * @property {string} updated_at - The date the repo was last updated in ISO8601 format.
+ * @property {string} language - The primary language the repo is written in.
+ * @property {string[]} topics - An array of topics associated with the repo - conventially in dxw this is used to list the owners of the repo (EG govpress, delivery-plus).
+ * @property {number} open_issues - The number of open issues on the repo.
+ * @property {string[]} dependencies - An array of dependencies used by the repo.
+ */
+
+/**
+ * @typedef {Object} StoredRepo
+ * @property {string} name - The name of the repo Eg "dalmation".
+ * @property {string} description - A brief description of the repo.
+ * @property {string} htmlUrl - The URL to the repo on GitHub for humans.
+ * @property {string} apiUrl - The URL to the repo on GitHub for computers.
+ * @property {string} pullsUrl - The API url to get more info on pull requests for this repo.
+ * @property {string} issuesUrl - The API url to get more info on issues for this repo.
+ * @property {string} updatedAt - The date the repo was last updated in ISO8601 format.
+ * @property {string} language - The primary language the repo is written in.
+ * @property {string[]} topics - An array of topics associated with the repo - conventially in dxw this is used to list the owners of the repo (EG govpress, delivery-plus).
+ * @property {number} openIssues - The number of open issues on the repo.
+ * @property {string[]} dependencies - An array of dependencies used by the repo.
+ */
+
+/**
+ * @typedef {StoredRepo} UiRepo
+ * @property {Date} date - The date the repo was last updated in JS date format.
+ */
+
+/**
+ * Maps from an API repo to a StoredRepo
+ * @param {ApiRepo} repo
+ * @returns {StoredRepo}
+ */
 export const mapRepoFromApiForStorage = (repo) => ({
   name: repo.name,
   description: repo.description,