gscan 5.3.3 → 5.3.4

package/bin/cli.js

@@ -1,8 +1,5 @@
 #!/usr/bin/env node
 
-// Remove all Node warnings before doing anything else
-process.removeAllListeners('warning');
-
 const prettyCLI = require('@tryghost/pretty-cli');
 const ui = require('@tryghost/pretty-cli').ui;
 const _ = require('lodash');
@@ -10,6 +7,51 @@ const {default: chalk} = require('chalk');
 const gscan = require('../lib');
 const ghostVersions = require('../lib/utils').versions;
 
+/**
+ * @typedef {object} CliArgv
+ * @property {string} themePath
+ * @property {boolean} [zip]
+ * @property {boolean} [v1]
+ * @property {boolean} [v2]
+ * @property {boolean} [v3]
+ * @property {boolean} [v4]
+ * @property {boolean} [v5]
+ * @property {boolean} [v6]
+ * @property {boolean} [canary]
+ * @property {boolean} [fatal]
+ * @property {boolean} [verbose]
+ * @property {string[]} [labs]
+ */
+
+/**
+ * @typedef {object} CheckOptions
+ * @property {'cli'} format
+ * @property {string} [checkVersion]
+ * @property {boolean} [verbose]
+ * @property {boolean} [onlyFatalErrors]
+ * @property {Record<string, true>} [labs]
+ */
+
+/**
+ * @typedef {object} ResultFailure
+ * @property {string} ref
+ * @property {string} [message]
+ */
+
+/**
+ * @typedef {object} FormattedResult
+ * @property {'error' | 'warning' | 'recommendation' | 'feature'} level
+ * @property {string} rule
+ * @property {string} details
+ * @property {ResultFailure[]} [failures]
+ */
+
+/**
+ * @typedef {object} FormattedTheme
+ * @property {string} checkedVersion
+ * @property {{error: FormattedResult[], warning: FormattedResult[], recommendation: FormattedResult[]}} results
+ */
+
 const levels = {
     error: chalk.red,
     warning: chalk.yellow,
@@ -17,115 +59,68 @@ const levels = {
     feature: chalk.green
 };
 
-const cliOptions = {
-    format: 'cli'
-};
+/**
+ * @param {CliArgv} argv
+ * @returns {CheckOptions}
+ */
+function resolveOptions(argv) {
+    /** @type {CheckOptions} */
+    const options = {format: 'cli'};
 
-prettyCLI
-    .configure({
-        name: 'gscan'
-    })
-    .groupOrder([
-        'Sources:',
-        'Utilities:',
-        'Commands:',
-        'Arguments:',
-        'Required Options:',
-        'Options:',
-        'Global Options:'
-    ])
-    .positional('<themePath>', {
-        paramsDesc: 'Theme folder or .zip file path',
-        mustExist: true
-    })
-    .boolean('-z, --zip', {
-        desc: 'Theme path points to a zip file'
-    })
-    .boolean('-1, --v1', {
-        desc: 'Check theme for Ghost 1.0 compatibility'
-    })
-    .boolean('-2, --v2', {
-        desc: 'Check theme for Ghost 2.0 compatibility'
-    })
-    .boolean('-3, --v3', {
-        desc: 'Check theme for Ghost 3.0 compatibility'
-    })
-    .boolean('-4, --v4', {
-        desc: 'Check theme for Ghost 4.0 compatibility'
-    })
-    .boolean('-5, --v5', {
-        desc: 'Check theme for Ghost 5.0 compatibility'
-    })
-    .boolean('-6, --v6', {
-        desc: 'Check theme for Ghost 6.0 compatibility'
-    })
-    .boolean('-c, --canary', {
-        desc: 'Check theme for Ghost 6.0 compatibility (alias for --v6)'
-    })
-    .boolean('-f, --fatal', {
-        desc: 'Only show fatal errors that prevent upgrading Ghost'
-    })
-    .boolean('--verbose', {
-        desc: 'Output check details'
-    })
-    .array('--labs', {
-        desc: 'a list of labs flags'
-    })
-    .parseAndExit()
-    .then((argv) => {
-        if (argv.v1) {
-            cliOptions.checkVersion = 'v1';
-        } else if (argv.v2) {
-            cliOptions.checkVersion = 'v2';
-        } else if (argv.v3) {
-            cliOptions.checkVersion = 'v3';
-        } else if (argv.v4) {
-            cliOptions.checkVersion = 'v4';
-        } else if (argv.v5) {
-            cliOptions.checkVersion = 'v5';
-        } else if (argv.v6) {
-            cliOptions.checkVersion = 'v6';
-        } else if (argv.canary) {
-            cliOptions.checkVersion = ghostVersions.canary;
-        } else {
-            cliOptions.checkVersion = ghostVersions.default;
-        }
+    if (argv.canary) {
+        options.checkVersion = ghostVersions.canary;
+    } else {
+        const versionKey = Object.keys(ghostVersions).find(k => k.startsWith('v') && argv[k]);
+        options.checkVersion = versionKey || ghostVersions.default;
+    }
 
-        cliOptions.verbose = argv.verbose;
-        cliOptions.onlyFatalErrors = argv.fatal;
+    options.verbose = argv.verbose;
+    options.onlyFatalErrors = argv.fatal;
 
-        if (argv.labs) {
-            cliOptions.labs = {};
+    if (argv.labs) {
+        options.labs = {};
 
-            argv.labs.forEach((flag) => {
-                cliOptions.labs[flag] = true;
-            });
-        }
+        argv.labs.forEach((flag) => {
+            options.labs[flag] = true;
+        });
+    }
 
-        if (cliOptions.onlyFatalErrors) {
-            ui.log(chalk.bold('\nChecking theme compatibility (fatal issues only)...'));
-        } else {
-            ui.log(chalk.bold('\nChecking theme compatibility...'));
-        }
+    return options;
+}
 
+/**
+ * @param {CliArgv} argv
+ * @param {CheckOptions} options
+ * @returns {Promise<void>}
+ */
+async function runCheck(argv, options) {
+    if (options.onlyFatalErrors) {
+        ui.log(chalk.bold('\nChecking theme compatibility (fatal issues only)...'));
+    } else {
+        ui.log(chalk.bold('\nChecking theme compatibility...'));
+    }
+
+    try {
+        const theme = argv.zip
+            ? await gscan.checkZip(argv.themePath, options)
+            : await gscan.check(argv.themePath, options);
+        outputResults(theme, options);
+    } catch (err) {
         if (argv.zip) {
-            gscan.checkZip(argv.themePath, cliOptions)
-                .then(theme => outputResults(theme, cliOptions))
-                .catch((error) => {
-                    ui.log(error);
-                });
+            ui.log(err);
         } else {
-            gscan.check(argv.themePath, cliOptions)
-                .then(theme => outputResults(theme, cliOptions))
-                .catch((err) => {
-                    ui.log(err.message);
-                    if (err.code === 'ENOTDIR') {
-                        ui.log('Did you mean to add the -z flag to read a zip file?');
-                    }
-                });
+            ui.log(err.message);
+            if (err.code === 'ENOTDIR') {
+                ui.log('Did you mean to add the -z flag to read a zip file?');
+            }
         }
-    });
+    }
+}
 
+/**
+ * @param {FormattedResult} result
+ * @param {CheckOptions} options
+ */
 function outputResult(result, options) {
     ui.log(levels[result.level](`- ${_.capitalize(result.level)}:`), result.rule);
 
@@ -153,10 +148,20 @@ function outputResult(result, options) {
     ui.log(''); // extra line-break
 }
 
+/**
+ * @param {string} word
+ * @param {number} count
+ * @returns {string}
+ */
 function formatCount(word, count) {
     return `${count} ${count === 1 ? word : `${word}s`}`;
 }
 
+/**
+ * @param {FormattedTheme} theme
+ * @param {CheckOptions} options
+ * @returns {string}
+ */
 function getSummary(theme, options) {
     let summaryText = '';
     const errorCount = theme.results.error.length;
@@ -195,15 +200,20 @@ function getSummary(theme, options) {
     return summaryText;
 }
 
+/**
+ * @param {*} theme - Raw theme object; mutated into FormattedTheme by gscan.format()
+ * @param {CheckOptions} options
+ */
 function outputResults(theme, options) {
     try {
+        /** @type {FormattedTheme} */
         theme = gscan.format(theme, options);
     } catch (err) {
         ui.log.error('Error formating result, some results may be missing.');
         ui.log.error(err);
     }
 
-    let errorCount = theme.results.error.length;
+    const errorCount = theme.results.error.length;
 
     ui.log('\n' + getSummary(theme, options));
 
@@ -229,7 +239,7 @@ function outputResults(theme, options) {
         _.each(theme.results.recommendation, rule => outputResult(rule, options));
     }
 
-    ui.log(`\nGet more help at ${chalk.cyan.underline('https://ghost.org/docs/themes/')}`);
+    ui.log(`\nGet more help at ${chalk.cyan.underline('https://docs.ghost.org/themes/')}`);
     ui.log(`You can also check theme compatibility at ${chalk.cyan.underline('https://gscan.ghost.org/')}`);
 
     // The CLI feature is mainly used to run gscan programatically in tests within themes.
@@ -244,3 +254,69 @@ function outputResults(theme, options) {
         process.exit(0);
     }
 }
+
+function main() {
+    prettyCLI
+        .configure({
+            name: 'gscan'
+        })
+        .groupOrder([
+            'Sources:',
+            'Utilities:',
+            'Commands:',
+            'Arguments:',
+            'Required Options:',
+            'Options:',
+            'Global Options:'
+        ])
+        .positional('<themePath>', {
+            paramsDesc: 'Theme folder or .zip file path',
+            mustExist: true
+        })
+        .boolean('-z, --zip', {
+            desc: 'Theme path points to a zip file'
+        })
+        .boolean('-1, --v1', {
+            desc: 'Check theme for Ghost 1.0 compatibility'
+        })
+        .boolean('-2, --v2', {
+            desc: 'Check theme for Ghost 2.0 compatibility'
+        })
+        .boolean('-3, --v3', {
+            desc: 'Check theme for Ghost 3.0 compatibility'
+        })
+        .boolean('-4, --v4', {
+            desc: 'Check theme for Ghost 4.0 compatibility'
+        })
+        .boolean('-5, --v5', {
+            desc: 'Check theme for Ghost 5.0 compatibility'
+        })
+        .boolean('-6, --v6', {
+            desc: 'Check theme for Ghost 6.0 compatibility'
+        })
+        .boolean('-c, --canary', {
+            desc: 'Check theme for Ghost 6.0 compatibility (alias for --v6)'
+        })
+        .boolean('-f, --fatal', {
+            desc: 'Only show fatal errors that prevent upgrading Ghost'
+        })
+        .boolean('--verbose', {
+            desc: 'Output check details'
+        })
+        .array('--labs', {
+            desc: 'a list of labs flags'
+        })
+        .parseAndExit()
+        .then((argv) => {
+            const options = resolveOptions(argv);
+            runCheck(argv, options);
+        });
+}
+
+module.exports = {formatCount, getSummary, outputResult, outputResults, resolveOptions, runCheck};
+
+if (require.main === module) {
+    // Remove all Node warnings only when run as a CLI, not when imported as a module
+    process.removeAllListeners('warning');
+    main();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gscan",
-  "version": "5.3.3",
+  "version": "5.3.4",
   "description": "Scans Ghost themes looking for errors, deprecations, features and compatibility",
   "keywords": [
     "ghost",
@@ -67,13 +67,17 @@
     "@eslint/eslintrc": "3.3.5",
     "@eslint/js": "10.0.1",
     "@tryghost/pro-ship": "1.0.7",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "4.0.18",
     "eslint": "10.0.3",
     "eslint-plugin-ghost": "3.5.0",
     "nodemon": "3.1.14",
     "should": "13.2.3",
     "sinon": "21.0.2",
-    "vitest": "^4.0.18"
+    "vitest": "4.0.18"
+  },
+  "resolutions": {
+    "node-loggly-bulk": "4.0.2",
+    "node-loggly-bulk/axios": "1.13.6"
   },
   "files": [
     "lib",