gscan 5.3.2 → 5.3.4

package/app/middlewares/log-request.js

@@ -1,13 +1,13 @@
-var randomUUID = require('crypto').randomUUID,
-    logging = require('@tryghost/logging');
+const randomUUID = require('crypto').randomUUID;
+const logging = require('@tryghost/logging');
 
 /**
  * @TODO:
  * - move middleware to ignition?
  */
 module.exports = function logRequest(req, res, next) {
-    var startTime = Date.now(),
-        requestId = randomUUID();
+    const startTime = Date.now();
+    const requestId = randomUUID();
 
     function logResponse() {
         res.responseTime = (Date.now() - startTime) + 'ms';

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/lib/ast-linter/helpers/index.js

@@ -49,8 +49,8 @@ function blockParamIndex(name, options) {
         depth < len;
         depth++
     ) {
-        let blockParams = options.blockParams[depth],
-            param = blockParams && blockParams.indexOf(name);
+        const blockParams = options.blockParams[depth];
+        const param = blockParams && blockParams.indexOf(name);
         if (blockParams && param >= 0) {
             return [depth, param];
         }

package/lib/ast-linter/linter.js

@@ -144,28 +144,16 @@ class Linter {
 
         scanner.accept(options.parsed.ast);
 
-        if (scanner.context.partials) {
-            this.partials = scanner.context.partials;
-        }
-
-        if (scanner.context.helpers) {
-            this.helpers = scanner.context.helpers.map(p => ({
-                name: p.node,
-                helperType: p.helperType
-            }));
-        }
+        this.partials = scanner.context.partials;
 
-        if (scanner.context.customThemeSettings) {
-            this.customThemeSettings = scanner.context.customThemeSettings;
-        }
+        this.helpers = scanner.context.helpers.map(p => ({
+            name: p.node,
+            helperType: p.helperType
+        }));
 
-        if (scanner.context.inlinePartials) {
-            this.inlinePartials = scanner.context.inlinePartials;
-        }
-
-        if (scanner.context.usedPageProperties) {
-            this.usedPageProperties = scanner.context.usedPageProperties;
-        }
+        this.customThemeSettings = scanner.context.customThemeSettings;
+        this.inlinePartials = scanner.context.inlinePartials;
+        this.usedPageProperties = scanner.context.usedPageProperties;
 
         return messages;
     }

package/lib/ast-linter/rules/internal/scope.js

@@ -51,6 +51,7 @@ const contexts = {
     pagination: {}
 };
 
+/* v8 ignore start */
 const helpers = { // eslint-disable-line no-unused-vars
     // {{get}} can return multiple different contexts depending on params
     get(node) {
@@ -91,6 +92,7 @@ const helpers = { // eslint-disable-line no-unused-vars
         };
     }
 };
+/* v8 ignore stop */
 
 function getTemplateContext(fileName) {
     if (fileName.match(/^post(-.*)?\.hbs/)) {

package/lib/ast-linter/rules/lint-no-unknown-custom-theme-select-value-in-match.js

@@ -17,14 +17,7 @@ function getCustomSettingValue(node) {
 module.exports = class NoUnknownCustomThemeSelectValueInMatch extends Rule {
     _checkForCustomThemeSelectValueInMatch(node) {
         if (node.path.original === 'match' && node.params.length === 3) {
-            if (node.params.length < 2 || node.params.length > 3) {
-                return;
-            }
-
-            let indexSecondParameter = 1; // Case {{match @custom.example "123"}}
-            if (node.params.length === 3) {
-                indexSecondParameter = 2; // Case {{match @custom.example "!=" "123"}}
-            }
+            const indexSecondParameter = 2; // Case {{match @custom.example "!=" "123"}}
             const setting = getCustomSettingName(node.params[0]) || getCustomSettingName(node.params[indexSecondParameter]);
             const value = getCustomSettingValue(node.params[0]) || getCustomSettingValue(node.params[indexSecondParameter]);
 

package/lib/checker.js

@@ -6,10 +6,8 @@ const debug = require('@tryghost/debug')('checker');
 const errors = require('@tryghost/errors');
 const versions = require('./utils').versions;
 
-// An object containing helpers as keys and their labs flag as values
-// E.g. match:  'matchHelper'
-const labsEnabledHelpers = {
-};
+// See lib/utils/labs-enabled-helpers.js to add/remove labs-flagged helpers
+const labsEnabledHelpers = require('./utils/labs-enabled-helpers');
 
 function loadChecks() {
     const checksDir = nodePath.join(__dirname, 'checks');

package/lib/checks/002-comment-id.js

@@ -16,7 +16,7 @@ const checkCommentID = function checkCommentID(theme, options) {
     });
     _.each(ruleSet, function (check, ruleCode) {
         _.each(theme.files, function (themeFile) {
-            var template = themeFile.file.match(/\.hbs$/);
+            const template = themeFile.file.match(/\.hbs$/);
 
             if (template) {
                 if (themeFile.content.match(check.regex)) {

package/lib/checks/080-helper-usage.js

@@ -17,7 +17,7 @@ module.exports = function checkUsage(theme, options) {
     });
     _.each(ruleSet, function (check, ruleCode) {
         _.each(theme.files, function (themeFile) {
-            var template = themeFile.file.match(/\.hbs$/);
+            const template = themeFile.file.match(/\.hbs$/);
             const validApi = check.validInAPI ? check.validInAPI.includes(targetApiVersion) : true;
             if (template) {
                 if (validApi && themeFile.content.match(check.regex)) {

package/lib/checks/100-custom-template-settings-usage.js

@@ -1,132 +1,5 @@
 const _ = require('lodash');
-const spec = require('../specs');
-const {versions} = require('../utils');
-const ASTLinter = require('../ast-linter');
-
-function getRules(id, options) {
-    const checkVersion = _.get(options, 'checkVersion', versions.default);
-    let ruleSet = spec.get([checkVersion]);
-
-    const ruleRegex = new RegExp('^' + id + '-.*', 'g');
-    ruleSet = _.pickBy(ruleSet.rules, function (rule, ruleCode) {
-        if (ruleCode.match(ruleRegex)) {
-            return rule;
-        }
-    });
-
-    return ruleSet;
-}
-
-function getLogger({theme, rule, file = null}) {
-    return {
-        failure: (content) => {
-            if (!theme.results.fail[rule.code]) {
-                theme.results.fail[rule.code] = {failures: []};
-            }
-            const failure = {
-                ...content,
-                rule: rule.code
-            };
-            if (file) {
-                failure.ref = file.file;
-            }
-            theme.results.fail[rule.code].failures.push(failure);
-        }
-    };
-}
-
-function applyRule(rule, theme) {
-    const partialVerificationCache = new Map();
-    // The result variable is passed around to keep a state through the full lifecycle
-    const result = {};
-    try {
-        // Check if the rule is enabled (optional)
-        if (typeof rule.isEnabled === 'function') {
-            if (!rule.isEnabled({theme, log: getLogger({theme, rule}), result})) {
-                return;
-            }
-        } else if (typeof rule.isEnabled === 'boolean' && !rule.isEnabled) {
-            return;
-        }
-
-        // Initialize the rule (optional)
-        if (typeof rule.init === 'function') {
-            rule.init({theme, log: getLogger({theme, rule}), result});
-        }
-
-        // Run the main function on each theme file (optional)
-        if (typeof rule.eachFile === 'function') {
-            _.each(theme.files , function (themeFile) {
-                rule.eachFile({file: themeFile, theme, log: getLogger({theme, rule}), result, partialVerificationCache});
-            });
-        }
-
-        // Run the final function
-        if (typeof rule.done === 'function') {
-            rule.done({theme, log: getLogger({theme, rule}), result});
-        }
-    } catch (e) {
-        // Output something instead of failing silently (should never happen)
-        // eslint-disable-next-line
-        console.error('gscan failure', e);
-    }
-}
-
-function parseWithAST({theme, log, file, rules, callback, partialVerificationCache}){
-    const linter = new ASTLinter();
-
-    // This rule is needed to find partials
-    // Partials are needed for a full parsing
-    if (!rules['mark-used-partials']) {
-        rules['mark-used-partials'] = require(`../ast-linter/rules/mark-used-partials`);
-    }
-
-    function processFile(themeFile) {
-        if (themeFile.parsed.error) {
-            // Ignore parsing errors, they are handled in 005
-            return;
-        }
-
-        const fileName = themeFile.file;
-        // Check if the file is a partial
-        const isPartial = fileName.startsWith('partials/');
-        // Skip if already cached (for partials only)
-        if (isPartial && partialVerificationCache.has(fileName)) {
-            return;
-        }
-
-        const astResults = linter.verify({
-            parsed: themeFile.parsed,
-            rules,
-            source: themeFile.content,
-            moduleId: themeFile.file
-        });
-
-        // Cache the result for this partial
-        if (isPartial) {
-            partialVerificationCache.set(fileName, astResults);
-        }
-
-        if (astResults.length) {
-            log.failure({
-                message: astResults[0].message
-            });
-        }
-
-        if (typeof callback === 'function') {
-            callback(linter);
-        }
-
-        linter.partials.forEach(({normalizedName}) => {
-            const partialFile = theme.files.find(f => f.normalizedFile === `partials/${normalizedName}.hbs`);
-            if (partialFile) {
-                processFile(partialFile);
-            }
-        });
-    }
-
-    return processFile(file);
-}
+const {getRules, applyRule, parseWithAST} = require('../utils/check-utils');
 
 const ruleImplementations = {
     'GS100-NO-UNUSED-CUSTOM-THEME-SETTING': {

package/lib/checks/110-page-builder-usage.js

@@ -1,134 +1,5 @@
 const _ = require('lodash');
-const spec = require('../specs');
-const {versions} = require('../utils');
-const ASTLinter = require('../ast-linter');
-
-function getRules(id, options) {
-    const checkVersion = _.get(options, 'checkVersion', versions.default);
-    let ruleSet = spec.get([checkVersion]);
-
-    const ruleRegex = new RegExp('^' + id + '-.*', 'g');
-    ruleSet = _.pickBy(ruleSet.rules, function (rule, ruleCode) {
-        if (ruleCode.match(ruleRegex)) {
-            return rule;
-        }
-    });
-
-    return ruleSet;
-}
-
-function getLogger({theme, rule, file = null}) {
-    return {
-        failure: (content) => {
-            if (!theme.results.fail[rule.code]) {
-                theme.results.fail[rule.code] = {failures: []};
-            }
-            const failure = {
-                ...content,
-                rule: rule.code
-            };
-            if (file) {
-                failure.ref = file.file;
-            }
-            theme.results.fail[rule.code].failures.push(failure);
-        }
-    };
-}
-
-function applyRule(rule, theme) {
-    const partialVerificationCache = new Map();
-
-    // The result variable is passed around to keep a state through the full lifecycle
-    const result = {};
-    try {
-        // Check if the rule is enabled (optional)
-        if (typeof rule.isEnabled === 'function') {
-            if (!rule.isEnabled({theme, log: getLogger({theme, rule}), result, options: rule.options})) {
-                return;
-            }
-        } else if (typeof rule.isEnabled === 'boolean' && !rule.isEnabled) {
-            return;
-        }
-
-        // Initialize the rule (optional)
-        if (typeof rule.init === 'function') {
-            rule.init({theme, log: getLogger({theme, rule}), result});
-        }
-
-        // Run the main function on each theme file (optional)
-        if (typeof rule.eachFile === 'function') {
-            _.each(theme.files, function (themeFile) {
-                rule.eachFile({file: themeFile, theme, log: getLogger({theme, rule}), result, partialVerificationCache});
-            });
-        }
-
-        // Run the final function
-        if (typeof rule.done === 'function') {
-            rule.done({theme, log: getLogger({theme, rule}), result});
-        }
-    } catch (e) {
-        // Output something instead of failing silently (should never happen)
-        // eslint-disable-next-line
-        console.error('gscan failure', e);
-    }
-}
-
-function parseWithAST({theme, log, file, rules, callback, partialVerificationCache}) {
-    const linter = new ASTLinter();
-
-    // This rule is needed to find partials
-    // Partials are needed for a full parsing
-    if (!rules['mark-used-partials']) {
-        rules['mark-used-partials'] = require(`../ast-linter/rules/mark-used-partials`);
-    }
-
-    function processFile(themeFile) {
-        if (themeFile.parsed.error) {
-            // Ignore parsing errors, they are handled in 005
-            return;
-        }
-
-        const fileName = themeFile.file;
-        // Check if the file is a partial
-        const isPartial = fileName.startsWith('partials/');
-        // Skip if already cached (for partials only)
-        if (isPartial && partialVerificationCache.has(fileName)) {
-            return;
-        }
-
-        const astResults = linter.verify({
-            parsed: themeFile.parsed,
-            rules,
-            source: themeFile.content,
-            moduleId: themeFile.file
-        });
-
-        // Cache the result for this partial
-        if (isPartial) {
-            partialVerificationCache.set(fileName, astResults);
-        }
-
-        if (astResults.length) {
-            log.failure({
-                message: astResults[0].message,
-                ref: themeFile.file
-            });
-        }
-
-        if (typeof callback === 'function') {
-            callback(linter);
-        }
-
-        linter.partials.forEach(({normalizedName}) => {
-            const partialFile = theme.files.find(f => f.normalizedFile === `partials/${normalizedName}.hbs`);
-            if (partialFile) {
-                processFile(partialFile);
-            }
-        });
-    }
-
-    return processFile(file);
-}
+const {getRules, applyRule, parseWithAST} = require('../utils/check-utils');
 
 const ruleImplementations = {
     'GS110-NO-MISSING-PAGE-BUILDER-USAGE': {

package/lib/checks/120-no-unknown-globals.js

@@ -49,7 +49,6 @@ function processFileFunction(files, failures, theme, partialsFound) {
             });
         }
 
-        theme.helpers = theme.helpers || {};
         linter.helpers.forEach((helper) => {
             if (!theme.helpers[helper.name]) {
                 theme.helpers[helper.name] = [];

package/lib/faker/index.js

@@ -1,5 +1,5 @@
-var fakeData = function fakeData(themeFile) {
-    var tag = {
+const fakeData = function fakeData(themeFile) {
+    const tag = {
         id: '345678901',
         name: 'hill',
         description: 'tag for hill',
@@ -9,7 +9,7 @@ var fakeData = function fakeData(themeFile) {
         url: 'http://talltalesofhighhills.com/tag/hill'
     };
 
-    var author = {
+    const author = {
         id: '234567890',
         name: 'John McHill',
         slug: 'john-mchill',
@@ -23,7 +23,7 @@ var fakeData = function fakeData(themeFile) {
         url: 'http:///talltalesofhighhills.com/author/john-mchill'
     };
 
-    var post = {
+    const post = {
         id: '123456789',
         title: 'The highs and lows of hills',
         slug: 'the-highs-and-low-of-hills',
@@ -43,7 +43,7 @@ var fakeData = function fakeData(themeFile) {
     };
 
     // Initialise data for index/home hbs templates
-    var postsData = {posts: [post], pagination: {}};
+    let postsData = {posts: [post], pagination: {}};
 
     if (themeFile.file.match(/^post/) || themeFile.file.match(/^page/)) {
         postsData = {post: post};

package/lib/format.js

@@ -31,13 +31,13 @@ const format = function format(theme, options = {}) {
     const checkVersion = _.get(options, 'checkVersion', versions.default);
     const ruleSet = spec.get([checkVersion]);
 
-    var processedCodes = [],
-        hasFatalErrors = false,
-        stats = {
-            error: 0,
-            warning: 0,
-            recommendation: 0
-        };
+    const processedCodes = [];
+    let hasFatalErrors = false;
+    const stats = {
+        error: 0,
+        warning: 0,
+        recommendation: 0
+    };
 
     theme.results.error = [];
     theme.results.warning = [];

package/lib/read-theme.js

@@ -24,12 +24,12 @@ const readThemeStructure = function readThemeFiles(themePath, subPath, arr) {
     themePath = path.join(themePath, '.');
     subPath = subPath || '';
 
-    var tmpPath = os.tmpdir(),
-        inTmp = themePath.substr(0, tmpPath.length) === tmpPath;
+    const tmpPath = os.tmpdir();
+    const inTmp = themePath.substr(0, tmpPath.length) === tmpPath;
 
     arr = arr || [];
 
-    var makeResult = function makeResult(result, subFilePath, ext, symlink) {
+    const makeResult = function makeResult(result, subFilePath, ext, symlink) {
         result.push({
             file: subFilePath,
             normalizedFile: normalizePath(subFilePath),
@@ -163,36 +163,36 @@ const processHelpers = function (theme, themeFile) {
  * this function is outsourced in the future, so it can be used by GScan and Ghost. But for now, we don't pre-optimise.
  */
 const extractCustomTemplates = function extractCustomTemplates(allTemplates) {
-    var toReturn = [],
-        generateName = function generateName(templateName) {
-            var name = templateName;
-
-            name = name.replace(/^(post-|page-|custom-)/, '');
-            name = name.replace(/-/g, ' ');
-            name = name.replace(/\b\w/g, function (letter) {
-                return letter.toUpperCase();
-            });
+    const toReturn = [];
+    const generateName = function generateName(templateName) {
+        let name = templateName;
+
+        name = name.replace(/^(post-|page-|custom-)/, '');
+        name = name.replace(/-/g, ' ');
+        name = name.replace(/\b\w/g, function (letter) {
+            return letter.toUpperCase();
+        });
 
-            return name.trim();
-        },
-        generateFor = function (templateName) {
-            if (templateName.match(/^page-/)) {
-                return ['page'];
-            }
+        return name.trim();
+    };
+    const generateFor = function (templateName) {
+        if (templateName.match(/^page-/)) {
+            return ['page'];
+        }
 
-            if (templateName.match(/^post-/)) {
-                return ['post'];
-            }
+        if (templateName.match(/^post-/)) {
+            return ['post'];
+        }
 
-            return ['page', 'post'];
-        },
-        generateSlug = function (templateName) {
-            if (templateName.match(/^custom-/)) {
-                return null;
-            }
+        return ['page', 'post'];
+    };
+    const generateSlug = function (templateName) {
+        if (templateName.match(/^custom-/)) {
+            return null;
+        }
 
-            return templateName.match(/^(page-|post-)(.*)/)[2];
-        };
+        return templateName.match(/^(page-|post-)(.*)/)[2];
+    };
 
     _.each(allTemplates, function (templateName) {
         if (templateName.match(/^(post-|page-|custom-)/) && !templateName.match(/\//)) {
@@ -223,7 +223,7 @@ const extractTemplates = function extractTemplates(allFiles) {
             return templates;
         }
 
-        var tplMatch = entry.file.match(/(.*)\.hbs$/);
+        const tplMatch = entry.file.match(/(.*)\.hbs$/);
         if (tplMatch) {
             templates.push(tplMatch[1]);
         }
@@ -239,7 +239,7 @@ const extractTemplates = function extractTemplates(allFiles) {
 module.exports = function readTheme(themePath) {
     return readThemeStructure(themePath)
         .then(function (themeFiles) {
-            var allTemplates = extractTemplates(themeFiles);
+            const allTemplates = extractTemplates(themeFiles);
 
             return readFiles({
                 path: themePath,
@@ -258,6 +258,8 @@ module.exports = function readTheme(themePath) {
         });
 };
 
+module.exports._private = {readFiles};
+
 /**
  * @typedef {Object} Theme
  * @param {string} path

package/lib/specs/v1.js

@@ -5,7 +5,7 @@
  */
 const oneLineTrim = require('../utils/one-line-trim');
 const docsBaseUrl = `https://ghost.org/docs/themes/`;
-let knownHelpers, templates, rules, ruleNext;
+let knownHelpers; let templates; let rules; let ruleNext;
 
 knownHelpers = [
     // Ghost

package/lib/utils/check-utils.js

@@ -0,0 +1,137 @@
+const _ = require('lodash');
+const spec = require('../specs');
+const {versions} = require('./');
+const ASTLinter = require('../ast-linter');
+
+function getRules(id, options) {
+    const checkVersion = _.get(options, 'checkVersion', versions.default);
+    let ruleSet = spec.get([checkVersion]);
+
+    const ruleRegex = new RegExp('^' + id + '-.*', 'g');
+    ruleSet = _.pickBy(ruleSet.rules, function (rule, ruleCode) {
+        if (ruleCode.match(ruleRegex)) {
+            return rule;
+        }
+    });
+
+    return ruleSet;
+}
+
+function getLogger({theme, rule, file = null}) {
+    return {
+        failure: (content) => {
+            if (!theme.results.fail[rule.code]) {
+                theme.results.fail[rule.code] = {failures: []};
+            }
+            const failure = {
+                ...content,
+                rule: rule.code
+            };
+            if (file) {
+                failure.ref = file.file;
+            }
+            theme.results.fail[rule.code].failures.push(failure);
+        }
+    };
+}
+
+function applyRule(rule, theme) {
+    const partialVerificationCache = new Map();
+    // The result variable is passed around to keep a state through the full lifecycle
+    const result = {};
+    try {
+        // Check if the rule is enabled (optional)
+        if (typeof rule.isEnabled === 'function') {
+            if (!rule.isEnabled({theme, log: getLogger({theme, rule}), result, options: rule.options})) {
+                return;
+            }
+        } else if (typeof rule.isEnabled === 'boolean' && !rule.isEnabled) {
+            return;
+        }
+
+        // Initialize the rule (optional)
+        if (typeof rule.init === 'function') {
+            rule.init({theme, log: getLogger({theme, rule}), result});
+        }
+
+        // Run the main function on each theme file (optional)
+        if (typeof rule.eachFile === 'function') {
+            _.each(theme.files, function (themeFile) {
+                rule.eachFile({file: themeFile, theme, log: getLogger({theme, rule}), result, partialVerificationCache});
+            });
+        }
+
+        // Run the final function
+        if (typeof rule.done === 'function') {
+            rule.done({theme, log: getLogger({theme, rule}), result});
+        }
+    } catch (e) {
+        // Output something instead of failing silently (should never happen)
+        // eslint-disable-next-line
+        console.error('gscan failure', e);
+    }
+}
+
+function parseWithAST({theme, log, file, rules, callback, partialVerificationCache}) {
+    const linter = new ASTLinter();
+
+    // This rule is needed to find partials
+    // Partials are needed for a full parsing
+    if (!rules['mark-used-partials']) {
+        rules['mark-used-partials'] = require(`../ast-linter/rules/mark-used-partials`);
+    }
+
+    function processFile(themeFile) {
+        if (themeFile.parsed.error) {
+            // Ignore parsing errors, they are handled in 005
+            return;
+        }
+
+        const fileName = themeFile.file;
+        // Check if the file is a partial
+        const isPartial = fileName.startsWith('partials/');
+        // Skip if already cached (for partials only)
+        if (isPartial && partialVerificationCache.has(fileName)) {
+            return;
+        }
+
+        const astResults = linter.verify({
+            parsed: themeFile.parsed,
+            rules,
+            source: themeFile.content,
+            moduleId: themeFile.file
+        });
+
+        // Cache the result for this partial
+        if (isPartial) {
+            partialVerificationCache.set(fileName, astResults);
+        }
+
+        if (astResults.length) {
+            log.failure({
+                message: astResults[0].message,
+                ref: themeFile.file
+            });
+        }
+
+        if (typeof callback === 'function') {
+            callback(linter);
+        }
+
+        linter.partials.forEach(({normalizedName}) => {
+            const partialFile = theme.files.find(f => f.normalizedFile === `partials/${normalizedName}.hbs`);
+            if (partialFile) {
+                processFile(partialFile);
+            }
+        });
+    }
+
+    return processFile(file);
+}
+
+module.exports = {
+    getRules,
+    getLogger,
+    applyRule,
+    parseWithAST
+};

package/lib/utils/labs-enabled-helpers.js

@@ -0,0 +1,16 @@
+// Mapping of helper names to their Ghost labs flag names.
+// When a Ghost feature is behind a labs flag, add the helper here
+// so GScan includes it in knownHelpers when the flag is enabled.
+//
+// Usage:
+//   1. Add an entry: { helperName: 'labsFlagName' }
+//   2. Ghost passes { labs: { labsFlagName: true } } to GScan
+//   3. GScan adds helperName to the spec's knownHelpers
+//   4. When the helper graduates from labs, remove the entry
+//
+// Example (from when match was behind a labs flag):
+//   module.exports = {
+//       match: 'matchHelper'
+//   };
+module.exports = {
+};

package/lib/utils/score-calculator.js

@@ -19,7 +19,7 @@ const levelWeights = {
 * @returns {Object}
  */
 const calcScore = function calcScore(results, stats) {
-    var maxScore, actualScore, balancedScore;
+    let maxScore; let actualScore; let balancedScore;
 
     maxScore = _.reduce(levelWeights, function (max, weight, level) {
         return max + (weight * stats[level]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gscan",
-  "version": "5.3.2",
+  "version": "5.3.4",
   "description": "Scans Ghost themes looking for errors, deprecations, features and compatibility",
   "keywords": [
     "ghost",
@@ -33,7 +33,7 @@
     "start": "node app/index.js",
     "dev": "NODE_ENV=development DEBUG=gscan:* nodemon",
     "lint": "eslint . --ext .js --cache",
-    "test": "NODE_ENV=testing c8 --check-coverage --branches 95 --functions 95 --lines 95 --statements 95 mocha test/*.test.js",
+    "test": "NODE_ENV=testing vitest run --coverage",
     "posttest": "yarn lint",
     "preship": "yarn test",
     "ship": "pro-ship",
@@ -44,14 +44,14 @@
   },
   "dependencies": {
     "@sentry/node": "10.42.0",
-    "@tryghost/config": "2.0.0",
-    "@tryghost/debug": "2.0.0",
-    "@tryghost/errors": "3.0.0",
-    "@tryghost/logging": "4.0.0",
+    "@tryghost/config": "2.0.2",
+    "@tryghost/debug": "2.0.2",
+    "@tryghost/errors": "3.0.2",
+    "@tryghost/logging": "4.0.2",
     "@tryghost/nql": "0.12.10",
-    "@tryghost/pretty-cli": "3.0.0",
-    "@tryghost/server": "2.0.0",
-    "@tryghost/zip": "3.0.0",
+    "@tryghost/pretty-cli": "3.0.2",
+    "@tryghost/server": "2.0.2",
+    "@tryghost/zip": "3.0.2",
     "chalk": "5.6.2",
     "express": "5.2.1",
     "express-handlebars": "7.1.3",
@@ -64,16 +64,20 @@
   },
   "devDependencies": {
     "@eslint/compat": "2.0.3",
+    "@eslint/eslintrc": "3.3.5",
     "@eslint/js": "10.0.1",
     "@tryghost/pro-ship": "1.0.7",
-    "c8": "11.0.0",
-    "eslint": "10.0.2",
+    "@vitest/coverage-v8": "4.0.18",
+    "eslint": "10.0.3",
     "eslint-plugin-ghost": "3.5.0",
-    "mocha": "11.7.5",
     "nodemon": "3.1.14",
-    "rewire": "9.0.1",
     "should": "13.2.3",
-    "sinon": "21.0.2"
+    "sinon": "21.0.2",
+    "vitest": "4.0.18"
+  },
+  "resolutions": {
+    "node-loggly-bulk": "4.0.2",
+    "node-loggly-bulk/axios": "1.13.6"
   },
   "files": [
     "lib",