gscan 4.25.3 → 4.26.0

package/lib/checks/010-package-json.js

@@ -261,7 +261,10 @@ module.exports = function checkPackageJSON(theme, options) {
             v4PackageJSONValidationRules,
             canaryPackageJSONValidationRules
         );
+        // Make these delete more declarative as the list grows
         delete packageJSONValidationRules.isNotPresentEngineGhostAPI;
+        delete packageJSONValidationRules.isv01EngineGhostAPI;
+        delete packageJSONValidationRules.isv2EngineGhostAPI;
 
         packageJSONConditionalRules = _.merge(
             {},

package/lib/checks/030-assets.js

@@ -1,17 +1,14 @@
 const _ = require('lodash');
-const path = require('path');
-const fs = require('fs');
 const spec = require('../specs');
 const versions = require('../utils').versions;
 
-const checkAssets = function checkAssets(theme, options, themePath) {
+const checkAssets = function checkAssets(theme, options) {
     const checkVersion = _.get(options, 'checkVersion', versions.default);
     const ruleSet = spec.get([checkVersion]);
 
     let ruleToCheck = 'GS030-ASSET-REQ';
     let failures = [];
     let assetMatch;
-    let stats;
 
     _.filter(theme.files, {ext: '.hbs'}).forEach(function (template) {
         try {
@@ -30,19 +27,10 @@ const checkAssets = function checkAssets(theme, options, themePath) {
     }
 
     ruleToCheck = 'GS030-ASSET-SYM';
-    failures = [];
-
-    theme.files.forEach(function (themeFile) {
-        try {
-            stats = fs.lstatSync(path.join(themePath, themeFile.file));
-
-            if (stats.isSymbolicLink()) {
-                failures.push({ref: themeFile.file});
-            }
-        } catch (err) {
-            // ignore
-        }
-    });
+    failures = theme
+        .files
+        .filter(f => f.symlink)
+        .map(f => ({ref: f.file}));
 
     if (failures.length > 0) {
         theme.results.fail[ruleToCheck] = {failures: failures};

package/lib/read-theme.js

@@ -29,16 +29,18 @@ const readThemeStructure = function readThemeFiles(themePath, subPath, arr) {
 
     arr = arr || [];
 
-    var makeResult = function makeResult(result, subFilePath, ext) {
+    var makeResult = function makeResult(result, subFilePath, ext, symlink) {
         result.push({
             file: subFilePath,
-            ext: ext
+            ext,
+            symlink
         });
         return result;
     };
 
-    return fs.readdir(themePath).then(function (files) {
-        return Promise.reduce(files, function (result, file) {
+    return fs.readdir(themePath, {withFileTypes: true}).then(function (files) {
+        return Promise.reduce(files, function (result, dirent) {
+            const file = dirent.name;
             var extMatch = file.match(/.*?(\.[0-9a-z]+$)/i),
                 subFilePath = path.join(subPath, file),
                 newPath = path.join(themePath, file);
@@ -60,14 +62,11 @@ const readThemeStructure = function readThemeFiles(themePath, subPath, arr) {
                     : result;
             }
 
-            // NOTE: lstat does not follow symlinks
-            return fs.lstat(newPath).then(function (statFile) {
-                if (statFile.isDirectory()) {
-                    return readThemeStructure(newPath, subFilePath, result);
-                } else {
-                    return makeResult(result, subFilePath, extMatch !== null ? extMatch[1] : undefined);
-                }
-            });
+            if (dirent.isDirectory()) {
+                return readThemeStructure(newPath, subFilePath, result);
+            } else {
+                return makeResult(result, subFilePath, extMatch !== null ? extMatch[1] : undefined, dirent.isSymbolicLink());
+            }
         }, arr);
     });
 };

package/lib/specs/canary.js

@@ -2,7 +2,7 @@ const _ = require('lodash');
 const oneLineTrim = require('common-tags/lib/oneLineTrim');
 const previousSpec = require('./v4');
 const ghostVersions = require('../utils').versions;
-const docsBaseUrl = `https://ghost.org/docs/api/handlebars-themes/`;
+const docsBaseUrl = `https://ghost.org/docs/themes/`;
 const prevDocsBaseUrl = `https://themes.ghost.org/v${ghostVersions.v5.docs}/docs/`;
 const prevDocsBaseUrlRegEx = new RegExp(prevDocsBaseUrl, 'g');
 
@@ -423,6 +423,51 @@ let rules = {
         regex: /{{\s*?post\.author\.cover\s*?}}/g,
         helper: '{{post.author.cover}}'
     },
+    'GS001-DEPR-AUTH-INCL': {
+        level: 'error',
+        fatal: true,
+        rule: `<code>include="author"</code> should be replaced with <code>include="authors"</code>`,
+        details: oneLineTrim`The usage of <code>{{#get "posts" include="author"}}</code> is deprecated and should be replaced with <code>{{#get "posts" include="authors"}}</code>.<br>
+        Find more information about the <code>{{get}}</code> helper <a href="${docsBaseUrl}helpers/get/" target=_blank>here</a>.`,
+        // This regex seems only to work properly with the escaped characters. Removing them resulted
+        // in not detecting the wrong usage.
+        regex: /{{\s*?#get.+include=("|')\s*?([\w\[\]]+,{1}\s*?)*?(\s*?author\s*?)(\s*,{1}\s?[\w\[\]]+)*?\s*?("|')(.*)}}/g, // eslint-disable-line no-useless-escape
+        helper: 'include="author"'
+    },
+    'GS001-DEPR-AUTH-FIELD': {
+        level: 'error',
+        fatal: true,
+        rule: `<code>fields="author"</code> should be replaced with <code>fields="authors"</code>`,
+        details: oneLineTrim`The usage of <code>{{#get "posts" fields="author"}}</code> is deprecated and should be replaced with
+        <code>{{#get "posts" fields="primary_author"}}</code> or <code>{{#get "posts" fields="authors.[#]"}}</code>.<br>
+        Find more information about the <code>{{get}}</code> helper <a href="${docsBaseUrl}helpers/get/" target=_blank>here</a>.`,
+        // This regex seems only to work properly with the escaped characters. Removing them resulted
+        // in not detecting the wrong usage.
+        regex: /{{\s*?#get.+fields=("|')\s*?([\w\[\]]+,{1}\s*?)*?(\s*?author\s*?)(\s*,{1}\s?[\w\[\]]+)*?\s*?("|')(.*)}}/g, // eslint-disable-line no-useless-escape
+        helper: 'fields="author"'
+    },
+    'GS001-DEPR-AUTH-FILT': {
+        level: 'error',
+        fatal: true,
+        rule: `<code>filter="author:[...]"</code> should be replaced with <code>filter="authors:[...]"</code>`,
+        details: oneLineTrim`The usage of <code>{{#get "posts" filter="author:[...]"}}</code> is deprecated and should be replaced with <code>{{#get "posts" filter="authors:[...]"}}</code>.<br>
+        Find more information about the <code>{{get}}</code> helper <a href="${docsBaseUrl}helpers/get/" target=_blank>here</a>.`,
+        // This regex seems only to work properly with the escaped characters. Removing them resulted
+        // in not detecting the wrong usage.
+        regex: /{{\s*?#get.+filter=("|')\s*?([\w\[\]]+,{1}\s*?)*?(\s*?author:).*("|')(.*)}}/g, // eslint-disable-line no-useless-escape
+        helper: 'filter="author:[...]"'
+    },
+    'GS001-DEPR-AUTHBL': {
+        level: 'error',
+        fatal: true,
+        rule: 'The <code>{{#author}}</code> block helper should be replaced with <code>{{#primary_author}}</code> or <code>{{#foreach authors}}...{{/foreach}}</code>',
+        details: oneLineTrim`The usage of <code>{{#author}}</code> block helper outside of <code>author.hbs</code> is deprecated and
+        should be replaced with <code>{{#primary_author}}</code> or <code>{{#foreach authors}}...{{/foreach}}</code>.<br>
+        Find more information about the <code>{{authors}}</code> helper <a href="${docsBaseUrl}helpers/authors/" target=_blank>here</a>.`,
+        regex: /{{\s*?#author\s*?}}/g,
+        notValidIn: 'author.hbs',
+        helper: '{{#author}}'
+    },
     'GS001-DEPR-PAIMG': {
         level: 'error',
         fatal: true,
@@ -434,6 +479,28 @@ let rules = {
         regex: /{{\s*?post\.author\.image\s*?}}/g,
         helper: '{{post.author.image}}'
     },
+    'GS001-DEPR-CON-AUTH': {
+        level: 'error',
+        fatal: true,
+        rule: `The <code>{{#if author.*}}</code> block helper should be replaced with <code>{{#if primary_author.*}}</code>
+        or <code>{{#if authors.[#].*}}</code>`,
+        details: oneLineTrim`The usage of <code>{{#if author.*}}</code> is deprecated and should be replaced with <code>{{#if primary_author.*}}</code>
+        or <code>{{#if authors.[#].*}}</code>.<br>
+        Find more information about the <code>{{authors}}</code> helper <a href="${docsBaseUrl}helpers/authors/" target=_blank>here</a>.`,
+        regex: /{{\s*?#if\s*?(author)(?:\.\w+)*?\s*?}}/g,
+        helper: '{{#if author.*}}'
+    },
+    'GS001-DEPR-CON-PAUTH': {
+        level: 'error',
+        fatal: true,
+        rule: `The <code>{{#if post.author.*}}</code> block helper should be replaced with <code>{{#if post.primary_author.*}}</code>
+        or <code>{{#if post.authors.[#].*}}</code>`,
+        details: oneLineTrim`The usage of <code>{{#if post.author.*}}</code> is deprecated and should be replaced with <code>{{#if post.primary_author.*}}</code>
+        or <code>{{#if post.authors.[#].*}}</code>.<br>
+        Find more information about the <code>{{authors}}</code> helper <a href="${docsBaseUrl}helpers/authors/" target=_blank>here</a>.`,
+        regex: /{{\s*?#if\s*?(?:post\.)(author)(?:\.\w+)*?\s*?}}/g,
+        helper: '{{#if post.author.*}}'
+    },
     'GS001-DEPR-CON-AC': {
         level: 'error',
         fatal: true,
@@ -477,6 +544,75 @@ let rules = {
         See the object attributes of <code>author</code> <a href="${docsBaseUrl}context/author/#author-object-attributes" target=_blank>here</a>.`,
         regex: /{{\s*?#if\s*?post\.author\.image\s*?}}/g,
         helper: '{{#if post.author.image}}'
+    },
+    'GS001-DEPR-SPL': {
+        level: 'error',
+        fatal: true,
+        rule: '<code>{{@site.permalinks}}</code> was removed',
+        details: oneLineTrim`With the introduction of Dynamic Routing, you can define multiple permalinks.<br>
+        The <code>{{@site.permalinks}}</code> property will therefore no longer be used and should be removed from the theme.
+        Find more information about the <code>@site</code> property <a href="${docsBaseUrl}helpers/site/" target=_blank>here</a>.`,
+        regex: /{{\s*?@site\.permalinks\s*?}}/g,
+        helper: '{{@site.permalinks}}'
+    },
+    'GS001-DEPR-BPL': {
+        level: 'error',
+        fatal: true,
+        rule: '<code>{{@blog.permalinks}}</code> was removed',
+        details: oneLineTrim`With the introduction of Dynamic Routing, you can define multiple permalinks.<br>
+        The <code>{{@blog.permalinks}}</code> property will therefore no longer be used and should be removed from the theme.
+        Find more information about Ghost data helpers <a href="${docsBaseUrl}/helpers/#data-helpers" target=_blank>here</a>.`,
+        regex: /{{\s*?@blog\.permalinks\s*?}}/g,
+        helper: '{{@blog.permalinks}}'
+    },
+    'GS001-DEPR-SGF': {
+        level: 'error',
+        fatal: true,
+        rule: 'Replace <code>{{@site.ghost_foot}}</code> with <code>{{ghost_foot}}</code>',
+        details: oneLineTrim`The usage of <code>{{@site.ghost_foot}}</code> is deprecated and should be replaced with <code>{{ghost_foot}}</code>.<br>
+        The <code>{{@site.ghost_foot}}</code> property will therefore no longer be used and should be removed from the theme.
+        Find more information about the <code>{{ghost_foot}}</code> property <a href="${docsBaseUrl}helpers/ghost_head_foot/" target=_blank>here</a>.`,
+        regex: /{{\s*?@site\.ghost_foot\s*?}}/g,
+        helper: '{{@site.ghost_foot}}'
+    },
+    'GS001-DEPR-SGH': {
+        level: 'error',
+        fatal: true,
+        rule: 'Replace <code>{{@site.ghost_head}}</code> with <code>{{ghost_head}}</code>',
+        details: oneLineTrim`The usage of <code>{{@site.ghost_head}}</code> is deprecated and should be replaced with <code>{{ghost_head}}</code>.<br>
+        The <code>{{@site.ghost_head}}</code> property will therefore no longer be used and should be removed from the theme.
+        Find more information about the <code>{{ghost_head}}</code> property <a href="${docsBaseUrl}helpers/ghost_head_foot/" target=_blank>here</a>.`,
+        regex: /{{\s*?@site\.ghost_head\s*?}}/g,
+        helper: '{{@site.ghost_head}}'
+    },
+    'GS001-DEPR-LANG': {
+        level: 'error',
+        fatal: true,
+        rule: 'The <code>{{lang}}</code> helper should be replaced with <code>{{@site.locale}}</code>',
+        details: oneLineTrim`Replace <code>{{lang}}</code> helper with <code>{{@site.locale}}</code>.<br>
+        The <code>{{lang}}</code> helper is removed in v5 version of Ghost and should not be used.
+        Find more information about the <code>@site.locale</code> property <a href="${docsBaseUrl}helpers/site/" target=_blank>here</a>.`,
+        regex: /{{\s*?lang\s*?}}/g,
+        helper: '{{lang}}'
+    },
+    'GS001-DEPR-SITE-LANG': {
+        level: 'error',
+        fatal: true,
+        rule: 'The <code>{{@site.lang}}</code> helper should be replaced with <code>{{@site.locale}}</code>',
+        details: oneLineTrim`Replace <code>{{@site.lang}}</code> helper with <code>{{@site.locale}}</code>.<br>
+        The <code>{{@site.lang}}</code> helper is removed in v5 version of Ghost and should not be used.
+        Find more information about the <code>@site.locale</code> property <a href="${docsBaseUrl}helpers/site/" target=_blank>here</a>.`,
+        regex: /@site\.lang/g,
+        helper: '{{@site.lang}}'
+    },
+    'GS001-DEPR-USER-GET': {
+        level: 'error',
+        fatal: true,
+        rule: `<code>{{#get "users"}}</code> should be replaced with <code>{{#get "authors"}}</code>`,
+        details: oneLineTrim`The usage of <code>{{#get "users"}}</code> is deprecated and will not return any data. It should be replaced with <code>{{#get "authors"}}</code>.<br>
+        Find more information about the <code>{{get}}</code> helper <a href="${docsBaseUrl}helpers/get/" target=_blank>here</a>.`,
+        regex: /{{\s*?#get ("|')\s*users("|')\s*/g,
+        helper: '{{#get "users"}}'
     }
 };
 

package/lib/specs/v2.js

@@ -403,7 +403,7 @@ let rules = {
         rule: '<code>{{@blog.permalinks}}</code> was removed',
         details: oneLineTrim`With the introduction of Dynamic Routing, you can define multiple permalinks.<br>
         The <code>{{@blog.permalinks}}</code> property will therefore no longer be used and should be removed from the theme.
-        Find more information about Ghost data helpers <a href="${docsBaseUrl}/helpers/data/" target=_blank>here</a>.`,
+        Find more information about Ghost data helpers <a href="${docsBaseUrl}/helpers/#data-helpers" target=_blank>here</a>.`,
         regex: /{{\s*?@blog\.permalinks\s*?}}/g,
         helper: '{{@blog.permalinks}}'
     },

package/lib/specs/v3.js

@@ -49,7 +49,7 @@ let rules = {
     'GS070-VALID-TRANSLATIONS': {
         level: 'error',
         rule: 'Theme translations must be parsable',
-        fatal: false, // @TODO (major): mark as fatal
+        fatal: false,
         details: oneLineTrim`Theme translations (located in <code>locales/*.json</code>) need to be readable by the node JSON parser, or they will not be applied.`
     }
 };

package/lib/specs/v4.js

@@ -2,7 +2,7 @@ const _ = require('lodash');
 const oneLineTrim = require('common-tags/lib/oneLineTrim');
 const previousSpec = require('./v3');
 const ghostVersions = require('../utils').versions;
-const docsBaseUrl = `https://ghost.org/docs/api/handlebars-themes/`;
+const docsBaseUrl = `https://ghost.org/docs/themes/`;
 const prevDocsBaseUrl = `https://themes.ghost.org/v${ghostVersions.v3.docs}/docs/`;
 const prevDocsBaseUrlRegEx = new RegExp(prevDocsBaseUrl, 'g');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gscan",
-  "version": "4.25.3",
+  "version": "4.26.0",
   "description": "Scans Ghost themes looking for errors, deprecations, features and compatibility",
   "keywords": [
     "ghost",
@@ -40,7 +40,7 @@
     "gscan": "./bin/cli.js"
   },
   "dependencies": {
-    "@sentry/node": "6.19.2",
+    "@sentry/node": "6.19.3",
     "@tryghost/config": "0.2.2",
     "@tryghost/debug": "0.1.11",
     "@tryghost/errors": "1.2.7",