chore: improve naming logic across scripts (#34)

This Pull request implements uniformity in property, parameters, and
general naming across scripts in `src/lib`; This changes approached the
naming by associating param properties to either main project repo,
forked repo or both, it also renamed some function based off of pure
logical name that made sense to the functionality performed by the
renamed function.

### Changes Made

- Renamed all project related repo details param and its branch ref
property to `projectRepoDetails` and `repoMainBranchRef` respectively;
Changes occurred across the listed scripts...
  - fork script
- Renamed all fork related repo details params and its branch ref
property to `forkedRepoDetails` and `repoChangeBranchRef` respectively;
this change signifies that actions taken on a forked repo is expected to
only occur on the change branch i.e. the branch created on forked repo
to make changes to; changes occurred on the listed scripts
  - word-editor script
- Renamed the `repo` param in `getBranch` function to `repoFullname` to
state explicitly that a repo fullname is expected by the function
- Renamed the `fork` param in `updateRepositoryFork` fucntion to
`forkedRepoFullname` to state explicitly that the forked repo fullname
is expected by the function
- Renamed `editExistingWord` function to `updateExistingWord` to better
state the function's logic

📖

Author: babblebey

src/lib/branch.js

@@ -33,12 +33,12 @@ export async function createBranch(userOctokit, repoDetails, newBranchName) {
 /**
  * Get a Branch/Ref details
  * @param {import("octokit").Octokit} userOctokit 
- * @param {string} repo 
+ * @param {string} repoFullname
  * @param {string} ref 
  * @returns Branch/Ref details
  */
-export async function getBranch(userOctokit, repo, ref) {
-  const { repoOwner, repoName } = getRepoParts(repo);
+export async function getBranch(userOctokit, repoFullname, ref) {
+  const { repoOwner, repoName } = getRepoParts(repoFullname);
   const formattedRef = ref.split("/")[0] === "refs" 
     ? ref.split("/").slice(1).join("/")
     : ref;

src/lib/fork.js

@@ -4,21 +4,22 @@ import { getRepoParts } from "./utils/index.js";
 /**
  * Fork the project (specified) Repo to user account
  * @param {import("octokit").Octokit} userOctokit 
- * @param {{ repoFullname: string, repoMainBranchRef: string }} repo 
+ * @param {{ repoFullname: string, repoMainBranchRef: string }} projectRepoDetails 
+ * @returns {string} fullname of forked repo - [userlogin]/jargons.dev
  */
-export async function forkRepository(userOctokit, repoDetails) {
-  const { repoFullname, repoMainBranchRef } = repoDetails;
+export async function forkRepository(userOctokit, projectRepoDetails) {
+  const { repoFullname, repoMainBranchRef } = projectRepoDetails;
   const { repoOwner, repoName } = getRepoParts(repoFullname);
 
   try {
     const { data: user } = await userOctokit.request("GET /user");
 
-    const fork = await isRepositoryForked(userOctokit, repoFullname, user.login ); 
+    const fork = await isRepositoryForked(userOctokit, repoFullname, user.login); 
 
     if (fork) {
       console.log("Repo is already forked!");
 
-      const { isUpdated, updateSHA } = await isRepositoryForkUpdated(userOctokit, repoDetails, fork)
+      const { isUpdated, updateSHA } = await isRepositoryForkUpdated(userOctokit, projectRepoDetails, fork)
 
       if (!isUpdated) {
         console.log("Repo is outdated!");
@@ -46,18 +47,21 @@ export async function forkRepository(userOctokit, repoDetails) {
 /**
  * Update (Sync) repository to state of main (head) repository
  * @param {import("octokit").Octokit} userOctokit 
- * @param {string} fork 
+ * @param {string} forkedRepoFullname
  * @param {{ ref: string, sha: string }} headRepoRef 
  */
-async function updateRepositoryFork(userOctokit, fork, headRepoRef) {
-  const { repoOwner, repoName } = getRepoParts(fork);
+async function updateRepositoryFork(userOctokit, forkedRepoFullname, headRepoRef) {
+  const { repoOwner, repoName } = getRepoParts(forkedRepoFullname);
   const { ref, sha } = headRepoRef;
+  const formattedRef = ref.split("/")[0] === "refs" 
+    ? ref.split("/").slice(1).join("/")
+    : ref;
 
   try {
     await userOctokit.request("PATCH /repos/{owner}/{repo}/git/refs/{ref}", {
       owner: repoOwner,
       repo: repoName,
-      ref, //-> `heads/${branchToSync}`
+      ref: formattedRef, //-> `heads/${branchToSync}`
       sha
     });
 
@@ -71,19 +75,20 @@ async function updateRepositoryFork(userOctokit, fork, headRepoRef) {
 /**
  * Check whether a fork is (in Sync with head repo) up-to-date with main repo  
  * @param {import("octokit").Octokit} userOctokit 
- * @param {{ repoFullname: string, repoMainBranchRef: string }} repoDetails 
- * @param {string} fork 
- * @returns {{ isUpdated: boolean, updateSHA: string }}
+ * @param {{ repoFullname: string, repoMainBranchRef: string }} projectRepoDetails 
+ * @param {string} forkedRepoFullname 
+ * @returns {Promise<{ isUpdated: boolean, updateSHA: string }>}
  */
-async function isRepositoryForkUpdated(userOctokit, repoDetails, fork) {
-  const { repoFullname, repoMainBranchRef } = repoDetails;
+async function isRepositoryForkUpdated(userOctokit, projectRepoDetails, forkedRepoFullname) {
+  const { repoFullname, repoMainBranchRef } = projectRepoDetails;
 
-  const userForkedBranch = await getBranch(userOctokit, fork, repoMainBranchRef);
-  const projectBranch = await getBranch(userOctokit, repoFullname, repoMainBranchRef);
+  // `repoMainBranchRef` because the forked repo's main should be compared again project's same main repo
+  const forkedRepoMainBranch = await getBranch(userOctokit, forkedRepoFullname, repoMainBranchRef);
+  const projectRepoMainBranch = await getBranch(userOctokit, repoFullname, repoMainBranchRef);
 
   return {
-    isUpdated: userForkedBranch.object.sha === projectBranch.object.sha,
-    updateSHA: projectBranch.object.sha
+    isUpdated: forkedRepoMainBranch.object.sha === projectRepoMainBranch.object.sha,
+    updateSHA: projectRepoMainBranch.object.sha
   };
 }
 
@@ -92,7 +97,7 @@ async function isRepositoryForkUpdated(userOctokit, repoDetails, fork) {
  * @param {import("octokit").Octokit} userOctokit 
  * @param {string} repoFullname 
  * @param {string} userLogin 
- * @returns { string | null }
+ * @returns {Promsise<string | null>}
  * 
  * @todo paginate response to get a list of all forks in one call
  */

src/lib/word-editor.js

@@ -4,13 +4,13 @@ import wordFileTemplate from "./template/word.md.js";
 /**
  * Write and add a new word to user's forked dictionary
  * @param {import("octokit").Octokit} userOctokit 
- * @param {{ repoFullname: string, repoBranchRef: string }} forkedRepoDetails 
+ * @param {{ repoFullname: string, repoChangeBranchRef: string }} forkedRepoDetails 
  * @param {{ title: string, content: string }} word 
  */
 export async function writeNewWord(userOctokit, forkedRepoDetails, { title, content }) {
-  const { repoFullname, repoBranchRef } = forkedRepoDetails;
+  const { repoFullname, repoChangeBranchRef } = forkedRepoDetails;
   const { repoOwner, repoName } = getRepoParts(repoFullname);
-  const branch = repoBranchRef.split("/").slice(2).join("/");
+  const branch = repoChangeBranchRef.split("/").slice(2).join("/");
   const wordFileContent = writeWordFileContent(title, content);
 
   try {
@@ -30,15 +30,15 @@ export async function writeNewWord(userOctokit, forkedRepoDetails, { title, cont
 }
 
 /**
- * Edit and update an existing word in user's forked dictionary
+ * Update an existing word in user's forked dictionary
  * @param {import("octokit").Octokit} userOctokit 
- * @param {{ repoFullname: string, repoBranchRef: string }} forkedRepoDetails 
+ * @param {{ repoFullname: string, repoChangeBranchRef: string }} forkedRepoDetails 
  * @param {{ path: string, sha: string, title: string, content: string }} word  enter new content as value to `content` property
  */
-export async function editExistingWord(userOctokit, forkedRepoDetails, { path, sha, title, content }) {
-  const { repoFullname, repoBranchRef } = forkedRepoDetails;
+export async function updateExistingWord(userOctokit, forkedRepoDetails, { path, sha, title, content }) {
+  const { repoFullname, repoChangeBranchRef } = forkedRepoDetails;
   const { repoOwner, repoName } = getRepoParts(repoFullname);
-  const branch = repoBranchRef.split("/").slice(2).join("/");
+  const branch = repoChangeBranchRef.split("/").slice(2).join("/");
   const wordFileContent = writeWordFileContent(title, content);
 
   try {
@@ -61,11 +61,11 @@ export async function editExistingWord(userOctokit, forkedRepoDetails, { path, s
 /**
  * Retrieve data for already existing word
  * @param {import("octokit").Octokit} userOctokit 
- * @param {{ repoFullname: string, repoBranchRef: string }} forkedRepoDetails 
+ * @param {{ repoFullname: string, repoBranchRef: string }} repoDetails 
  * @param {string} wordTitle 
  */
-export async function getExistingWord(userOctokit, forkedRepoDetails, wordTitle) {
-  const { repoFullname, repoBranchRef } = forkedRepoDetails;
+export async function getExistingWord(userOctokit, repoDetails, wordTitle) {
+  const { repoFullname, repoBranchRef } = repoDetails;
   const { repoOwner, repoName } = getRepoParts(repoFullname);
 
   try {