Update files headers and documentation

index.js

@@ -1,3 +1,13 @@
+/**
+ * @file index.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Entry point to the command line tool
+ *
+ * It parses the arguments passed to the command line tool and decides which module to invoke
+ */
 const minimist = require('minimist')
 const shell = require('shelljs')
 

src/bump/index.js

@@ -1,3 +1,15 @@
+/**
+ * @file src/bump/index.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Entry point for bump command
+ *
+ * This command (pkp-plugin bump) runs on a plugins root folder (containing version.xml).
+ * It provides an interactive CLI to collect the new version and release date of the plugin,
+ * then updates the XML file.
+ */
 const xml2js = require('xml2js')
 const inquirer = require('inquirer')
 const chalk = require('chalk')

src/bump/readVersionFIle.js

@@ -1,3 +1,14 @@
+/**
+ * @file src/bump/readVersionFile.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Helper for reading the version of the plugin
+ *
+ * This helper is used by the bump command (pkp-plugin bump) to read the current version of the plugin
+ * from version.xml.
+ */
 const { readFile } = require('../utils/files')
 
 const readVersionFile = async fileName => {

src/help.js

@@ -1,3 +1,12 @@
+/**
+ * @file src/help.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ *
+ * @brief Prints the help of the command line (when running pkp-plugin help)
+ */
 const chalk = require('chalk')
 const { log, warn, info } = require('./utils/log')
 

src/release/buildRelease.js

@@ -1,3 +1,15 @@
+/**
+ * @file src/release/buildRelease.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Helper for building a release (used by pkp-plugin release command)
+ *
+ * This helper performs these actions:
+ * - prompts the user to run any extra build commands in the current folder (gulp build, composer install etc..)
+ * - creates a Tar file from the current folder (in preparation to uploading it as an asset to the Github release)
+ */
 const { error, log, info } = require('../utils/log')
 const inquirer = require('inquirer')
 const execa = require('execa')

src/release/createGithubRelease.js

@@ -1,3 +1,21 @@
+/**
+ * @file src/release/createGithubRelease.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Helper for building a release (used by pkp-plugin release command)
+ *
+ * This helper performs these actions:
+ * - Prompts the user to confirm they want to create a release on Github
+ * - Opens the URL for Github release prepopulated with the release info
+ * - Waits for the user to confirm they have published the release
+ * 
+ * @notes 
+ * - We can not automatically know when the user has published the release so we require manual confirmation
+ *  - using open({wait: true}) could be used but it triggers when the browser is closed (not the tab),
+ *  also it does not work on windows
+ */
 const inquirer = require('inquirer')
 const execa = require('execa')
 const open = require('open')

src/release/createTag.js

@@ -1,3 +1,16 @@
+/**
+ * @file src/release/createTag.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Helper for building a release (used by pkp-plugin release command)
+ *
+ * This helper performs these actions:
+ * - commit the change
+ * - tags the commit (the user can update the default tag suggested)
+ * - push the tag to Github
+ */
 const inquirer = require('inquirer')
 const execa = require('execa')
 const process = require('process')

src/release/index.js

@@ -1,3 +1,14 @@
+/**
+ * @file src/release/index.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Entry point for release command
+ *
+ * This entry point only parses arguments. Orchestrating the work is handled by publishRelease module.
+ * 
+ */
 const { warn, info } = require('../utils/log')
 const publishRelease = require('./publishRelease')
 

src/release/publishRelease.js

@@ -1,3 +1,16 @@
+/**
+ * @file src/release/index.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Helper for building a release (used by pkp-plugin release command)
+ *
+ * This helper is the actual entry point for the operations performed by the command.
+ * It was abstracted in a separate module to separate from parsing command lines argument
+ * in cases where the command is executed when prompted after running pkp-plugin bump
+ * (as opposed to when it's run with pkp-plugin release newversion 2.0.0) 
+ */
 const execa = require('execa')
 const buildRelease = require('./buildRelease')
 const git = require('../utils/git')

src/release/uploadRelease.js

@@ -1,3 +1,15 @@
+/**
+ * @file src/release/uploadRelease.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Helper for uploading a release to Github (used by pkp-plugin release command)
+ *
+ * This helper performs these actions:
+ * - prompts the user for Github token (or uses the one from env variable)
+ * - uses Github API to upload the release tar file (built by buildRelease in previous step) to Github
+ */
 const inquirer = require('inquirer')
 const { Octokit } = require('@octokit/rest')
 const chalk = require('chalk')

src/utils/checkSumFile.js

@@ -1,9 +1,19 @@
-const crypto = require('crypto')
-const fs = require('fs')
 /**
- * Calculates the md5 check sum of a file
+ * @file src/utils/checkSumFile.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ *
+ * @brief Helper function to calculate the md5 check sum of a file
+ *
+ * This calculates checksum of a file (defaulting to MD5) and provides an easier
+ * promise-based interface to creating a hash with crypto package
  */
-module.exports = function checksumFile (path, hashName = 'md5') {
+const crypto = require('crypto')
+const fs = require('fs')
+
+module.exports = function checksumFile(path, hashName = 'md5') {
   return new Promise((resolve, reject) => {
     const hash = crypto.createHash(hashName)
     const stream = fs.createReadStream(path)

src/utils/downloadPackage.js

@@ -1,9 +1,19 @@
+/**
+ * @file src/utils/downloadPackage.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ *
+ * @brief Helper function to download a file
+ *
+ * Downloads a file from the internet taking into consideration follwing a redirect
+ * which is needed for Github links
+ *
+ */
 const https = require('follow-redirects').https
 const fs = require('fs')
 
-/**
- * Downloads a file from the internet following the redirect (which is needed for Github links)
- */
 module.exports = (package, fileName) => {
   return new Promise((resolve, reject) => {
     const file = fs.createWriteStream(fileName)

src/utils/files.js

@@ -1,3 +1,13 @@
+/**
+ * @file src/utils/files.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @module files
+ *
+ * @brief Helpers to promisify and simplify reading and writing files
+ */
 const fs = require('fs')
 
 const readFile = (fileName, encoding = 'utf8') => {

src/utils/getNextVersion.js

@@ -1,3 +1,12 @@
+/**
+ * @file src/utils/getNextVersion.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Helper to try and guess the next version of a plugin based on the current version (found in version.xml)
+ *
+ */
 const getNextVersion = currentVersion => {
   try {
     const numbers = currentVersion.split('.').map(char => Number(char))

src/utils/git.js

@@ -1,3 +1,12 @@
+/**
+ * @file src/utils/git.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Git helpers for some operations needed by the tool
+ *
+ */
 const execa = require('execa')
 const githubUrlFromGit = require('github-url-from-git')
 const { log } = require('./log')

src/utils/log.js

@@ -1,3 +1,16 @@
+/**
+ * @file src/utils/log.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @module log
+ *
+ * @brief Wrapper around logging functions
+ *
+ * Provides a wrapper around console.log, info, error to consolidate the use of colors
+ * for different log actions (coloring using chalk library)
+ */
 const chalk = require('chalk')
 
 const info = (...args) => {

src/utils/plugins/extractAllReleasesFromXml.js

@@ -1,17 +1,26 @@
-const xml2js = require('xml2js')
-
-const { readFile } = require('../files')
-const { info } = require('../log')
-
-const parser = new xml2js.Parser()
-
 /**
+ * @file src/utils/plugins/extractAllReleasesFromXml.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ *
+ * @brief Helper function to extract all releases from a Plugin Gallery xml file
+ *
  * The function loops through the plugins and their releases and creates a text file containing a list
  * of the releases and their MD5 sums This is then consument by the bash script "checkMD5sum" that
  * downloads all the releases and compares their MD5 sums with the content of the generated file
  *
  * @param {string} filePath the path to the file to parse and extract the releases info from
+ *
  */
+const xml2js = require('xml2js')
+
+const { readFile } = require('../files')
+const { info } = require('../log')
+
+const parser = new xml2js.Parser()
+
 const extractData = async filePath => {
   info(`Extracting releases from ${filePath}`)
 

src/validate-all-releases/index.js

@@ -1,12 +1,22 @@
+/**
+ * @file src/validate-all-releases/index.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Entry point for validate-all-releases command
+ *
+ * This command (used by CI on Plugin Gallery repository) runs several checks on plugins.xml file:
+ * - Find all plugins and their releases in the XML file
+ * - Downloads all releases
+ * - Validates their MD5 checksum
+ */
 const shell = require('shelljs')
 const extractReleases = require('../utils/plugins/extractAllReleasesFromXml')
 const { writeFile } = require('../utils/files')
 const { info, error } = require('../utils/log')
 const execa = require('execa')
 
-/**
- * Entry point for validate-all-releases command
- */
 module.exports = async args => {
   try {
     const inputFilePath = getFilePathFromArgs(args)

src/validate-new-release/extractReleaseDataFromDiff.js

@@ -1,6 +1,15 @@
 /**
- * scraps a fragment of xml to get the package url, MD5 etc..
+ * @file src/validate-new-release/extractReleaseDataFromDiff.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
  * @param {string} lines the diffed lines showing what changed in a plugins.xml file
+ *
+ * @brief Helper function to extract release data from a diff
+ *
+ * The function parses the output of a diff to find the package information
+ * (its url and MD5 namely)
  */
 const extractReleaseData = lines => {
   const { groups: { package } = {} } =

src/validate-new-release/index.js

@@ -1,3 +1,19 @@
+/**
+ * @file src/validate-new-release/index.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ *
+ * @brief Entry point for validate-new-release command
+ *
+ * This command runs on Git checkout of Plugin Gallery repository
+ * and validates new releases added to the file. Some of the checks:
+ * - Extracts the release and md5 data from diff
+ * - Downloads the package specified in the release
+ * - Validates the MD5 of the package downloaded
+ * - Checks the contents of the tar file of the package are valid
+ */
 const shell = require('shelljs')
 const downloadPackage = require('../utils/downloadPackage')
 const extractReleaseDataFromDiff = require('./extractReleaseDataFromDiff')

src/validate-new-release/validateTarContents.js

@@ -1,10 +1,19 @@
+/**
+ * @file src/validate-new-release/validateTarContents.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ *
+ * @brief Helper function to validate the conents of package
+ *
+ * Validates the contents of tarball, namely it checks whether a downloaded package
+ * contains one folder matching the plugin name
+ */
 const shell = require('shelljs')
 const { log } = require('../utils/log')
 const extractAllReleasesFromXml = require('../utils/plugins/extractAllReleasesFromXml')
 
-/**
- * Validates the contents of tarball (checks that it contains one folder matching the plugin name)
- */
 module.exports = async (
   { tarFile, md5, packageUrl },
   pluginsFilePath = './plugins.xml'

src/version.js

@@ -1,3 +1,11 @@
+/**
+ * @file src/version.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file LICENSE.
+ *
+ * @brief Prints the current version of the command line tool (run with pkp-plugin version)
+ */
 const { info } = require('./utils/log')
 
 module.exports = args => {