gscan 4.37.1 → 4.37.3

package/lib/ast-linter/helpers/index.js

@@ -16,6 +16,9 @@ function getNodeName(node) {
 
     case 'PathExpression':
     default:
+        if (node.data){
+            return `@${node.parts.join('.')}`;
+        }
         if (node.parts) {
             return node.parts[0];
         }

package/lib/ast-linter/linter.js

@@ -20,6 +20,7 @@ class Linter {
         this.helpers = [];
         this.inlinePartials = [];
         this.customThemeSettings = [];
+        this.usedPageProperties = [];
     }
 
     /**
@@ -57,7 +58,8 @@ class Linter {
                 partials: [],
                 helpers: [],
                 inlinePartials: [],
-                customThemeSettings: []
+                customThemeSettings: [],
+                usedPageProperties: []
             };
         }
         Scanner.prototype = new Handlebars.Visitor();
@@ -161,6 +163,10 @@ class Linter {
             this.inlinePartials = scanner.context.inlinePartials;
         }
 
+        if (scanner.context.usedPageProperties) {
+            this.usedPageProperties = scanner.context.usedPageProperties;
+        }
+
         return messages;
     }
 }

package/lib/ast-linter/rules/base.js

@@ -9,6 +9,8 @@ module.exports = class BaseRule {
         this.helpers = options.helpers;
         this.inlinePartials = options.inlinePartials || [];
         this.customThemeSettings = options.customThemeSettings;
+        // TODO: remove hardcoded list of known page builder properties once we have a way to get them from the spec
+        this.knownPageBuilderProperties = options.knownPageBuilderProperties || ['show_title_and_feature_image'];
     }
 
     getVisitor({fileName} = {}) {
@@ -160,6 +162,10 @@ module.exports = class BaseRule {
         return this.helpers && this.helpers.includes(nodeName);
     }
 
+    isValidPageBuilderProperty(property) {
+        return this.knownPageBuilderProperties && this.knownPageBuilderProperties.includes(property);
+    }
+
     isValidCustomThemeSettingReference(name) {
         return this.customThemeSettings && !!this.customThemeSettings[name];
     }

package/lib/ast-linter/rules/index.js

@@ -12,10 +12,11 @@ module.exports = {
     'GS090-NO-PRICE-DATA-CURRENCY-GLOBAL': require('./lint-no-price-data-currency-global'),
     'GS090-NO-PRICE-DATA-CURRENCY-CONTEXT': require('./lint-no-price-data-currency-context'),
     'GS090-NO-PRICE-DATA-MONTHLY-YEARLY': require('./lint-no-price-data-monthly-yearly'),
+    'GS110-NO-UNKNOWN-PAGE-BUILDER-USAGE': require('./lint-no-unknown-page-properties'),
+    'GS120-NO-UNKNOWN-GLOBALS': require('./lint-no-unknown-globals'),
     'no-multi-param-conditionals': require('./lint-no-multi-param-conditionals'),
     'no-nested-async-helpers': require('./lint-no-nested-async-helpers'),
     'no-prev-next-post-outside-post-context': require('./lint-no-prev-next-post-outside-post-context'),
-    'no-unknown-globals': require('./lint-no-unknown-globals'),
     'no-unknown-partials': require('./lint-no-unknown-partials'),
     'no-unknown-helpers': require('./lint-no-unknown-helpers')
 };

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

@@ -1,29 +1,35 @@
 const {getNodeName} = require('../../helpers');
 const _ = require('lodash');
 
-const globals = {
-    site: {
-        url: true,
-        title: true,
-        description: true,
-        icon: true,
-        logo: true,
-        cover_image: true,
-        twitter: true,
-        facebook: true,
-        navigation: true,
-        timezone: true,
-        lang: true
-    },
-    config: {
-        posts_per_page: true
-    },
-    labs: {
-        publicAPI: true,
-        subscribers: true
-    }
+// TODO: the allowlist should include all properties of these top-level globals
+const ghostGlobals = {
+    site: true,
+    member: true,
+    setting: true, // TODO: we should remove this but the Journal theme is using it atm
+    config: true,
+    labs: true,
+    custom: true
+};
+
+// unless we update AST to check that we're within a foreach block, we need to allowlist all of these as they look the same as globals
+const dataVars = {
+    index: true,
+    number: true,
+    key: true,
+    first: true,
+    last: true,
+    odd: true,
+    even: true,
+    rowStart: true,
+    rowEnd: true
 };
 
+// unless we move from lodash to a glob match, we just need to handle all custom since we can't allowlist those
+function isOnAllowlist(parts) {
+    const variable = parts && parts[0];
+    return ghostGlobals[variable] || dataVars[variable] || false;
+}
+
 // true = property exists
 // 'context' = has context's shape
 // ['context] = array of context's shape
@@ -218,10 +224,18 @@ class Scope {
         return matchedFrame && matchedFrame.node;
     }
 
-    isLocal(node) {
-        // @foo MustacheStatements are referencing globals rather than locals
+    isKnownVariable(node) {
+        // @foo statements are referencing globals rather than locals
+        //  and can be detected with the data: true attribute (???)
+
+        // they can be direct [Mustache] statements {{@foo}}...
         if (node.type === 'MustacheStatement' && node.path.data) {
-            return _.get(globals, node.path.parts.join('.'));
+            return isOnAllowlist(node.path.parts);
+        }
+
+        // ... or indirect using helpers, e.g. {{#match @foo.bar}}{{/match}}
+        if (node.type === 'PathExpression') {
+            return isOnAllowlist(node.parts);
         }
 
         let name = getNodeName(node);

package/lib/ast-linter/rules/lint-no-unknown-globals.js

@@ -2,8 +2,8 @@ const Rule = require('./base');
 const {logNode} = require('../helpers');
 
 module.exports = class NoUnknownGlobals extends Rule {
-    _checkForUnknownGlobal(node) {
-        if (node.path.data && !this.scope.isLocal(node)) {
+    _checkMustacheForUnknownGlobal(node) {
+        if (node.path.data && !this.scope.isKnownVariable(node)) {
             this.log({
                 message: `${logNode(node)} is not a known global`,
                 line: node.loc && node.loc.start.line,
@@ -13,9 +13,25 @@ module.exports = class NoUnknownGlobals extends Rule {
         }
     }
 
+    _checkBlockForUnknownGlobal(node) {
+        if (node.path.type === 'PathExpression') {
+            node.params.forEach((param) => {
+                if (param.data && !this.scope.isKnownVariable(param)) {
+                    this.log({
+                        message: `${logNode(param)} is not a known global`,
+                        line: param.loc && param.loc.start.line,
+                        column: param.loc && param.loc.start.column,
+                        source: this.sourceForNode(param)
+                    });
+                }
+            });
+        }
+    }
+
     visitor() {
         return {
-            MustacheStatement: this._checkForUnknownGlobal.bind(this)
+            MustacheStatement: this._checkMustacheForUnknownGlobal.bind(this),
+            BlockStatement: this._checkBlockForUnknownGlobal.bind(this)
         };
     }
 };

package/lib/ast-linter/rules/lint-no-unknown-page-properties.js

@@ -0,0 +1,21 @@
+const Rule = require('./base');
+const {logNode} = require('../helpers');
+
+module.exports = class NoUnknownPageProperties extends Rule {
+    _checkForUnknownPageProperty(node) {
+        if (node.data && node.parts && node.parts[0] === 'page' && (node.parts.length > 2 || !this.isValidPageBuilderProperty(node.parts[1]))) {
+            this.log({
+                message: `${logNode(node)} is not a known @page property`,
+                line: node.loc && node.loc.start.line,
+                column: node.loc && node.loc.start.column,
+                source: this.sourceForNode(node)
+            });
+        }
+    }
+
+    visitor() {
+        return {
+            PathExpression: this._checkForUnknownPageProperty.bind(this)
+        };
+    }
+};

package/lib/ast-linter/rules/mark-used-page-properties.js

@@ -0,0 +1,15 @@
+const Rule = require('./base');
+
+module.exports = class MarkUsedPageProperties extends Rule {
+    _markUsedPageProperties(node) {
+        if (node.data && node.parts && node.parts.length === 2 && node.parts[0] === 'page') {
+            this.scanner.context.usedPageProperties.push(node.parts[1]);
+        }
+    }
+
+    visitor() {
+        return {
+            PathExpression: this._markUsedPageProperties.bind(this)
+        };
+    }
+};

package/lib/checks/090-template-syntax.js

@@ -73,6 +73,7 @@ const checkTemplateSyntax = function checkTemplateSyntax(theme, options) {
 
         const linter = new ASTLinter({
             partials: theme.partials,
+            inlinePartials: [],
             helpers: [],
             customThemeSettings: customThemeSettings
         });

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

@@ -0,0 +1,185 @@
+const _ = require('lodash');
+const spec = require('../specs');
+const {versions, normalizePath} = 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) {
+    // 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});
+            });
+        }
+
+        // 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}) {
+    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 astResults = linter.verify({
+            parsed: themeFile.parsed,
+            rules,
+            source: themeFile.content,
+            moduleId: themeFile.file
+        });
+
+        if (astResults.length) {
+            log.failure({
+                message: astResults[0].message
+            });
+        }
+
+        if (typeof callback === 'function') {
+            callback(linter);
+        }
+
+        linter.partials.forEach(({node: partial}) => {
+            const partialFile = theme.files.find(f => normalizePath(f.file) === `partials/${normalizePath(partial)}.hbs`);
+            if (partialFile) {
+                processFile(partialFile);
+            }
+        });
+    }
+
+    return processFile(file);
+}
+
+const ruleImplementations = {
+    'GS110-NO-MISSING-PAGE-BUILDER-USAGE': {
+        isEnabled: ({options}) => {
+            // TODO: change to `isEnabled: true` when removing labs flag
+            return options && options.labs && options.labs.pageImprovements;
+        },
+        init: ({result}) => {
+            result.pageBuilderProperties = new Set();
+        },
+        eachFile: ({file, theme, log, result}) => {
+            const templateTest = file.file.match(/(?<!partials\/.+?)\.hbs$/);
+
+            if (templateTest) {
+                parseWithAST({file, theme, rules: {
+                    'mark-used-page-properties': require(`../ast-linter/rules/mark-used-page-properties`)
+                }, log, callback: (linter) => {
+                    linter.usedPageProperties.forEach((variable) => {
+                        result.pageBuilderProperties.add(variable);
+                    });
+                }});
+            }
+        },
+        done: ({log, result}) => {
+            // TODO: get this from the spec rather than hard-coding to account for version changes
+            const knownPageBuilderProperties = ['show_title_and_feature_image'];
+            const notUsedProperties = knownPageBuilderProperties.filter(x => !result.pageBuilderProperties.has(x));
+
+            notUsedProperties.forEach((property) => {
+                log.failure({
+                    ref: `@page.${property}`
+                });
+            });
+        }
+    },
+    'GS110-NO-UNKNOWN-PAGE-BUILDER-USAGE': {
+        isEnabled: ({options}) => {
+            // TODO: change to `isEnabled: true` when removing labs flag
+            return options && options.labs && options.labs.pageImprovements;
+        },
+        eachFile: ({file, theme, log}) => {
+            const templateTest = file.file.match(/(?<!partials\/.+?)\.hbs$/);
+
+            if (templateTest) {
+                parseWithAST({
+                    file, theme, rules: {
+                        'no-unknown-page-properties': require(`../ast-linter/rules/lint-no-unknown-page-properties`)
+                    }, log, callback: () => {}
+                });
+            }
+        }
+    }
+};
+
+function checkUsage(theme, options) {
+    const rules = getRules('GS110', options);
+
+    _.each(rules, function (check, ruleCode) {
+        applyRule({
+            code: ruleCode,
+            ...check,
+            ...ruleImplementations[ruleCode],
+            options
+        }, theme);
+    });
+
+    return theme;
+}
+
+module.exports = checkUsage;

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

@@ -0,0 +1,136 @@
+const _ = require('lodash');
+const spec = require('../specs');
+const versions = require('../utils').versions;
+const ASTLinter = require('../ast-linter');
+const {normalizePath} = require('../utils');
+
+function processFileFunction(files, failures, theme, partialsFound) {
+    const processedFiles = [];
+
+    return function processFile(linter, themeFile, parentInlinePartials = []) {
+        if (processedFiles.includes(themeFile.file)) {
+            return;
+        }
+
+        processedFiles.push(themeFile.file);
+
+        // Reset inline partial variables
+        linter.inlinePartials = [];
+        linter.options.inlinePartials = [];
+
+        linter.verify({
+            parsed: themeFile.parsed,
+            rules: [
+                require('../ast-linter/rules/mark-declared-inline-partials')
+            ],
+            source: themeFile.content,
+            moduleId: themeFile.file
+        });
+
+        // Store the inline partials for the actual partial linting
+        const inlinePartials = linter.inlinePartials;
+        linter.options.inlinePartials = [...inlinePartials, ...parentInlinePartials];
+
+        const astResults = linter.verify({
+            parsed: themeFile.parsed,
+            rules: [
+                require('../ast-linter/rules/mark-used-partials'),
+                require('../ast-linter/rules/lint-no-unknown-globals')
+            ],
+            source: themeFile.content,
+            moduleId: themeFile.file
+        });
+
+        if (astResults.length) {
+            astResults.forEach((result) => {
+                failures.push({
+                    ref: themeFile.file,
+                    message: result.message
+                });
+            });
+        }
+
+        theme.helpers = theme.helpers || {};
+        linter.helpers.forEach((helper) => {
+            if (!theme.helpers[helper.name]) {
+                theme.helpers[helper.name] = [];
+            }
+            theme.helpers[helper.name].push(themeFile.file);
+        });
+
+        linter.partials.forEach((partial) => {
+            const partialName = partial.node;
+            partialsFound[partialName] = true;
+            const file = files.find(f => normalizePath(f.file) === `partials/${normalizePath(partialName)}.hbs`);
+            if (file) {
+                // Find all inline partial declaration that were within the partial usage block
+                const childrenInlinePartials = [...parentInlinePartials];
+                for (const inline of inlinePartials) {
+                    //Only partials that are in scope
+                    if (inline.parents.some(node => node.type === partial.type &&
+                        node.loc.source === partial.loc.source &&
+                        node.loc.start.line === partial.loc.start.line &&
+                        node.loc.start.column === partial.loc.start.column &&
+                        node.loc.end.line === partial.loc.end.line &&
+                        node.loc.end.column === partial.loc.end.column)) {
+                        // Override the `parents` attribute as the inline partials are in another context than the children file
+                        childrenInlinePartials.push({
+                            ...inline,
+                            parents: []
+                        });
+                    }
+                }
+                processFile(linter, file, childrenInlinePartials);
+            }
+        });
+    };
+}
+
+const checkNoUnknownGlobals = function checkNoUnknownGlobals(theme, options) {
+    const failures = [];
+    const checkVersion = _.get(options, 'checkVersion', versions.default);
+    const ruleSet = spec.get([checkVersion]);
+
+    let partialsFound = {};
+
+    // Reset theme.helpers to make sure we only get helpers that are used
+    theme.helpers = {};
+
+    // CASE: 001-deprecations checks only needs `rules` that start with `GS001-DEPR-`
+    const ruleRegex = /GS120-.*/g;
+
+    const rulesToCheck = _.pickBy(ruleSet.rules, function (rule, ruleCode) {
+        if (ruleCode.match(ruleRegex)) {
+            return rule;
+        }
+    });
+
+    const processFile = processFileFunction(theme.files, failures, theme, partialsFound);
+
+    _.each(rulesToCheck, function (check, ruleCode) {
+        const linter = new ASTLinter({
+            partials: theme.partials,
+            helpers: ruleSet.knownHelpers
+        });
+
+        _.each(theme.files, function (themeFile) {
+            let templateTest = themeFile.file.match(/(?<!partials\/.+?)\.hbs$/);
+
+            if (templateTest) {
+                processFile(linter, themeFile);
+            }
+        });
+
+        theme.partials = Object.keys(partialsFound);
+
+        if (failures.length > 0) {
+            theme.results.fail[ruleCode] = {failures: failures};
+        } else {
+            theme.results.pass.push(ruleCode);
+        }
+    });
+
+    return theme;
+};
+
+module.exports = checkNoUnknownGlobals;

package/lib/specs/canary.js

@@ -712,6 +712,13 @@ let rules = {
         rule: '<code>package.json</code> property <code>config.custom</code> contains an entry with a <code>description</code> that is too long',
         details: oneLineTrim`<code>config.custom</code> entry <code>description</code> should be less than <code>100</code> characters so that it is displayed correctly.<br />
         Check the <a href="${docsBaseUrl}custom-settings" target=_blank><code>config.custom</code> documentation</a> for further information.`
+    },
+
+    'GS120-NO-UNKNOWN-GLOBALS': {
+        level: 'error',
+        rule: 'Unknown global helper used',
+        details: oneLineTrim`A global helper was detected that is not supported by this version of Ghost. Check the 
+        <a href="${docsBaseUrl}helpers/" target=_blank>helpers documentation</a> for further information.`
     }
 };
 

package/lib/specs/v1.js

@@ -387,7 +387,7 @@ rules = {
         level: 'error',
         rule: 'Templates must contain valid Handlebars',
         fatal: true,
-        details: oneLineTrim`Oops! You seemed to have used invalid Handlebars syntax. This mostly happens, when you use a helper that is not supported.<br>
+        details: oneLineTrim`Oops! You seemed to have used invalid Handlebars syntax. This mostly happens when you use a helper that is not supported.<br>
         See the full list of available helpers <a href="${docsBaseUrl}helpers/" target=_blank>here</a>.`
     },
     'GS010-PJ-REQ': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gscan",
-  "version": "4.37.1",
+  "version": "4.37.3",
   "description": "Scans Ghost themes looking for errors, deprecations, features and compatibility",
   "keywords": [
     "ghost",
@@ -40,7 +40,7 @@
     "gscan": "./bin/cli.js"
   },
   "dependencies": {
-    "@sentry/node": "7.56.0",
+    "@sentry/node": "7.60.1",
     "@tryghost/config": "0.2.17",
     "@tryghost/debug": "0.1.25",
     "@tryghost/errors": "1.2.25",
@@ -59,7 +59,7 @@
     "multer": "1.4.4",
     "pluralize": "8.0.0",
     "require-dir": "1.2.0",
-    "semver": "7.5.3",
+    "semver": "7.5.4",
     "uuid": "9.0.0",
     "validator": "13.0.0"
   },
@@ -68,7 +68,7 @@
     "eslint-plugin-ghost": "2.1.0",
     "istanbul": "0.4.5",
     "mocha": "10.0.0",
-    "node-fetch": "3.3.1",
+    "node-fetch": "3.3.2",
     "nodemon": "2.0.7",
     "rewire": "6.0.0",
     "should": "13.2.3",