gscan 4.37.2 → 4.37.4

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/rules/index.js

@@ -13,10 +13,10 @@ module.exports = {
     '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,36 @@
 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,
+    page: 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 +225,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/checks/110-page-builder-usage.js

@@ -116,10 +116,7 @@ function parseWithAST({theme, log, file, rules, callback}) {
 
 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;
-        },
+        isEnabled: true,
         init: ({result}) => {
             result.pageBuilderProperties = new Set();
         },
@@ -143,16 +140,14 @@ const ruleImplementations = {
 
             notUsedProperties.forEach((property) => {
                 log.failure({
-                    ref: `@page.${property}`
+                    ref: `page.hbs`,
+                    message: `@page.${property} is not used`
                 });
             });
         }
     },
     'GS110-NO-UNKNOWN-PAGE-BUILDER-USAGE': {
-        isEnabled: ({options}) => {
-            // TODO: change to `isEnabled: true` when removing labs flag
-            return options && options.labs && options.labs.pageImprovements;
-        },
+        isEnabled: true,
         eachFile: ({file, theme, log}) => {
             const templateTest = file.file.match(/(?<!partials\/.+?)\.hbs$/);
 

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

@@ -713,20 +713,24 @@ let rules = {
         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.`
     },
-
     'GS110-NO-MISSING-PAGE-BUILDER-USAGE': {
         level: 'warning',
-        rule: 'Not all page builder features are being used',
-        // TODO: get proper docs link
-        details: oneLineTrim`Some page builder features used via the <code>{{@page}}</code> global are not being used.&nbsp;
-        Check the <a href="${docsBaseUrl}page-builder" target=_blank>page builder documentation</a> for further information.`
+        rule: 'Not all page features are being used',
+        details: oneLineTrim`Some page features used by Ghost via the <code>{{@page}}</code> global are not implemented in this theme.&nbsp;
+        Find more information about the <code>{{@page}}</code> global <a href="${docsBaseUrl}helpers/page/" target=_blank>here</a>.`
     },
-
     'GS110-NO-UNKNOWN-PAGE-BUILDER-USAGE': {
         level: 'error',
         fatal: true,
         rule: 'Unsupported page builder feature used',
-        details: oneLineTrim`A page builder feature used via the <code>{{@page}}</code> global was detected but it's not supported by this version of Ghost.`
+        details: oneLineTrim`A page feature used via the <code>{{@page}}</code> global was detected but it's not supported by this version of Ghost.&nbsp;
+        Find more information about the <code>{{@page}}</code> global <a href="${docsBaseUrl}helpers/page/" target=_blank>here</a>.`
+    },
+    '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.2",
+  "version": "4.37.4",
   "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.60.0",
+    "@sentry/node": "7.60.1",
     "@tryghost/config": "0.2.17",
     "@tryghost/debug": "0.1.25",
     "@tryghost/errors": "1.2.25",