gscan 5.3.3 → 5.3.5

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.5",
   "description": "Scans Ghost themes looking for errors, deprecations, features and compatibility",
   "keywords": [
     "ghost",
@@ -43,15 +43,15 @@
     "gscan": "./bin/cli.js"
   },
   "dependencies": {
-    "@sentry/node": "10.42.0",
-    "@tryghost/config": "2.0.2",
-    "@tryghost/debug": "2.0.2",
-    "@tryghost/errors": "3.0.2",
-    "@tryghost/logging": "4.0.2",
+    "@sentry/node": "10.43.0",
+    "@tryghost/config": "2.0.3",
+    "@tryghost/debug": "2.0.3",
+    "@tryghost/errors": "3.0.3",
+    "@tryghost/logging": "4.0.3",
     "@tryghost/nql": "0.12.10",
-    "@tryghost/pretty-cli": "3.0.2",
-    "@tryghost/server": "2.0.2",
-    "@tryghost/zip": "3.0.2",
+    "@tryghost/pretty-cli": "3.0.3",
+    "@tryghost/server": "2.0.3",
+    "@tryghost/zip": "3.0.3",
     "chalk": "5.6.2",
     "express": "5.2.1",
     "express-handlebars": "7.1.3",
@@ -67,17 +67,20 @@
     "@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.1.0",
     "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.1.0"
+  },
+  "resolutions": {
+    "node-loggly-bulk": "4.0.2",
+    "node-loggly-bulk/axios": "1.13.6"
   },
   "files": [
     "lib",
-    "bin",
-    "app"
+    "bin"
   ]
 }

package/app/ghost-version.js

@@ -1,39 +0,0 @@
-const debug = require('@tryghost/debug')('ghost-version');
-const exec = require('child_process').exec;
-const config = require('@tryghost/config');
-
-let ttl;
-let ghostVersion;
-
-const fetchGhostVersion = function fetchGhostVersion() {
-    debug('Ghost version not set or ttl expired');
-    exec('npm show ghost version', function (err, stdout, stderr) {
-        if (err) {
-            debug('fetchGhostVersion err', err);
-        }
-
-        if (stderr) {
-            debug('fetchGhostVersion stderr', stderr);
-        }
-
-        if (stdout) {
-            debug('fetchGhostVersion stdout', stdout);
-            ghostVersion = stdout;
-            ttl = new Date(Date.now() + config.get('ghostVersionTTL')).valueOf();
-        }
-    });
-};
-
-const middleware = function middleware(req, res, next) {
-    if (!ghostVersion || ttl && ttl < Date.now()) {
-        fetchGhostVersion();
-    }
-
-    debug('res.locals.ghostVersion: ' + ghostVersion);
-    res.locals.ghostVersion = ghostVersion;
-    next();
-};
-
-fetchGhostVersion();
-
-module.exports = middleware;

package/app/index.js

@@ -1,154 +0,0 @@
-// Init Sentry middleware
-require('./middlewares/sentry');
-const sentry = require('@sentry/node');
-
-// Require rest of the modules
-const express = require('express');
-const debug = require('@tryghost/debug')('app');
-const {create} = require('express-handlebars');
-const multer = require('multer');
-const server = require('@tryghost/server');
-const config = require('@tryghost/config');
-const errors = require('@tryghost/errors');
-const gscan = require('../lib');
-const fs = require('fs-extra');
-const path = require('path');
-const logRequest = require('./middlewares/log-request');
-const uploadValidation = require('./middlewares/upload-validation');
-const ghostVer = require('./ghost-version');
-const ghostVersions = require('../lib/utils').versions;
-const upload = multer({dest: __dirname + '/uploads/'});
-const app = express();
-const viewsDir = path.join(__dirname, 'tpl');
-const scanHbs = create({
-    extname: '.hbs',
-    partialsDir: path.join(viewsDir, 'partials'),
-    layoutsDir: path.join(viewsDir, 'layouts'),
-    defaultLayout: 'default',
-    helpers: {
-        block(name, options) {
-            const root = options.data && options.data.root;
-
-            if (!root) {
-                return typeof options.fn === 'function' ? options.fn(this) : '';
-            }
-
-            const blockCache = root.blockCache || {};
-            let val = blockCache[name];
-
-            if (val === undefined && typeof options.fn === 'function') {
-                val = options.fn(this);
-            }
-
-            if (Array.isArray(val)) {
-                val = val.join('\n');
-            }
-
-            return val;
-        },
-        contentFor(name, options) {
-            const root = options.data && options.data.root;
-
-            if (!root) {
-                return '';
-            }
-
-            const blockCache = root.blockCache || (root.blockCache = {});
-            const block = blockCache[name] || (blockCache[name] = []);
-            block.push(options.fn(this));
-            return '';
-        }
-    }
-});
-
-// Configure express
-app.set('x-powered-by', false);
-app.set('query parser', false);
-
-app.engine('hbs', scanHbs.engine);
-
-app.set('view engine', 'hbs');
-app.set('views', viewsDir);
-
-app.use(logRequest);
-app.use(express.static(__dirname + '/public'));
-app.use(ghostVer);
-
-app.get('/', function (req, res) {
-    res.render('index', {ghostVersions});
-});
-
-app.post('/',
-    upload.single('theme'),
-    uploadValidation,
-    function (req, res, next) {
-        const zip = {
-            path: req.file.path,
-            name: req.file.originalname
-        };
-        const options = {
-            checkVersion: req.body.version || ghostVersions.default
-        };
-
-        debug('Uploaded: ' + zip.name + ' to ' + zip.path);
-        debug('Version to check: ' + options.checkVersion);
-
-        let checkError;
-
-        gscan.checkZip(zip, options)
-            .then(function processResult(theme) {
-                debug('Checked: ' + zip.name);
-                res.theme = theme;
-            }).catch(function (error) {
-                checkError = error;
-            }).finally(function () {
-                debug('attempting to remove: ' + req.file.path);
-                fs.remove(req.file.path)
-                    .catch(function (removeError) {
-                        debug('failed to remove uploaded file', removeError);
-                    })
-                    .then(function () {
-                        if (checkError) {
-                            debug('Calling next with error');
-                            return next(checkError);
-                        }
-
-                        debug('Calling next');
-                        return next();
-                    });
-            });
-    },
-    function doRender(req, res) {
-        const options = {
-            checkVersion: req.body.version || ghostVersions.default
-        };
-        debug('Formatting result');
-        const result = gscan.format(res.theme, options);
-        debug('Rendering result');
-        scanHbs.handlebars.logger.level = 0;
-        res.render('result', result);
-    }
-);
-
-app.use(function (req, res, next) {
-    next(new errors.NotFoundError({message: 'Page not found'}));
-});
-
-// eslint-disable-next-line no-unused-vars
-app.use(function (err, req, res, next) {
-    let template = 'error';
-    req.err = err;
-
-    let statusCode = err.statusCode || 500;
-    res.status(statusCode);
-
-    if (res.statusCode === 404) {
-        template = 'error-404';
-    }
-
-    res.render(template, {message: err.message, stack: err.stack, details: err.errorDetails, context: err.context});
-});
-
-sentry.setupExpressErrorHandler(app);
-
-server.start(app, config.get('port'));

package/app/middlewares/log-request.js

@@ -1,30 +0,0 @@
-const randomUUID = require('crypto').randomUUID;
-const logging = require('@tryghost/logging');
-
-/**
- * @TODO:
- * - move middleware to ignition?
- */
-module.exports = function logRequest(req, res, next) {
-    const startTime = Date.now();
-    const requestId = randomUUID();
-
-    function logResponse() {
-        res.responseTime = (Date.now() - startTime) + 'ms';
-        req.requestId = requestId;
-        req.userId = req.user ? (req.user.id ? req.user.id : req.user) : null;
-
-        if (req.err) {
-            logging.error({req: req, res: res, err: req.err});
-        } else {
-            logging.info({req: req, res: res});
-        }
-
-        res.removeListener('finish', logResponse);
-        res.removeListener('close', logResponse);
-    }
-
-    res.on('finish', logResponse);
-    res.on('close', logResponse);
-    next();
-};

package/app/middlewares/sentry.js

@@ -1,11 +0,0 @@
-const sentryDSN = process.env.SENTRY_DSN;
-
-if (sentryDSN) {
-    const Sentry = require('@sentry/node');
-    const version = require('../../package.json').version;
-    Sentry.init({
-        dsn: sentryDSN,
-        release: 'gscan@' + version,
-        environment: process.env.NODE_ENV
-    });
-}

package/app/middlewares/upload-validation.js

@@ -1,43 +0,0 @@
-// NOTE: this middleware was extracted from Ghost core validation for theme uploads
-//       might be useful to unify this logic in the future if it's extracted to separate module
-const path = require('path');
-const errors = require('@tryghost/errors');
-
-const checkFileExists = function checkFileExists(fileData) {
-    return !!(fileData.mimetype && fileData.path);
-};
-
-const checkFileIsValid = function checkFileIsValid(fileData, types, extensions) {
-    const type = fileData.mimetype;
-
-    if (types.includes(type) && extensions.includes(fileData.ext)) {
-        return true;
-    }
-
-    return false;
-};
-
-module.exports = function uploadValidation(req, res, next) {
-    const extensions = ['.zip'];
-    const contentTypes = ['application/zip', 'application/x-zip-compressed', 'application/octet-stream'];
-
-    req.file = req.file || {};
-    req.file.name = req.file.originalname;
-    req.file.type = req.file.mimetype;
-
-    if (!checkFileExists(req.file)) {
-        return next(new errors.ValidationError({
-            message: `"Please select a zip file.`
-        }));
-    }
-
-    req.file.ext = path.extname(req.file.name).toLowerCase();
-
-    if (!checkFileIsValid(req.file, contentTypes, extensions)) {
-        return next(new errors.UnsupportedMediaTypeError({
-            message: 'Please select a valid zip file.'
-        }));
-    }
-
-    next();
-};