gscan 6.1.0 → 6.2.1

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

@@ -9,7 +9,7 @@ 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
+        // Keep in sync with `pageBuilderProperties` in lib/specs/v5.js.
         this.knownPageBuilderProperties = options.knownPageBuilderProperties || ['show_title_and_feature_image'];
     }
 

package/lib/ast-linter/rules/lint-no-unknown-custom-theme-settings.js

@@ -6,7 +6,7 @@ module.exports = class NoUnknownCustomThemeSettings extends Rule {
             const name = node.parts[1];
             if (!this.isValidCustomThemeSettingReference(name)) {
                 this.log({
-                    message: `Missing Custom Theme Setting: "${name}"`,
+                    message: `Unknown {{@custom.${name}}} on line ${node.loc && node.loc.start.line}: ${this.sourceForNode(node)}`,
                     line: node.loc && node.loc.start.line,
                     column: node.loc && node.loc.start.column,
                     source: this.sourceForNode(node)

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

@@ -19,7 +19,8 @@ module.exports = class NoUnknownPartials extends Rule {
                     }
                     if (node.type === 'PartialStatement') {
                         return this.log({
-                            message: `Inlined dynamic partials like <code>{{> (dynamicPartial) }}</code> can result in page errors if the partial does not exist, use block dynamic partials instead.`,
+                            code: 'GS005-NO-INLINE-DYNAMIC-PARTIAL',
+                            message: `Inline dynamic partial on line ${logObject.line}: ${logObject.source}`,
                             ...logObject
                         });
                     }

package/lib/checks/005-template-compile.js

@@ -43,9 +43,11 @@ function processFileFunction(files, failures, theme, partialsFound) {
         });
 
         if (astResults.length) {
+            const first = astResults[0];
             failures.push({
                 ref: themeFile.file,
-                message: astResults[0].message
+                message: first.message,
+                ...(first.code ? {code: first.code} : {})
             });
         }
 
@@ -86,6 +88,8 @@ function processFileFunction(files, failures, theme, partialsFound) {
     };
 }
 
+const DEFAULT_CODE = 'GS005-TPL-ERR';
+
 const checkTemplatesCompile = function checkTemplatesCompile(theme, options) {
     const failures = [];
     const checkVersion = _.get(options, 'checkVersion', versions.default);
@@ -96,35 +100,34 @@ const checkTemplatesCompile = function checkTemplatesCompile(theme, options) {
     // 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 = /GS005-.*/g;
-
     const rulesToCheck = _.pickBy(ruleSet.rules, function (rule, ruleCode) {
-        if (ruleCode.match(ruleRegex)) {
-            return rule;
-        }
+        return /^GS005-/.test(ruleCode);
     });
 
     const processFile = processFileFunction(theme.files, failures, theme, partialsFound);
 
-    _.each(rulesToCheck, function (check, ruleCode) {
-        const linter = new ASTLinter({
-            partials: theme.partials,
-            helpers: ruleSet.knownHelpers
-        });
+    const linter = new ASTLinter({
+        partials: theme.partials,
+        helpers: ruleSet.knownHelpers
+    });
 
-        _.each(theme.files, function (themeFile) {
-            let templateTest = themeFile.file.match(/(?<!partials\/.+?)\.hbs$/);
+    _.each(theme.files, function (themeFile) {
+        if (themeFile.normalizedFile.endsWith('.hbs') && !themeFile.normalizedFile.startsWith('partials/')) {
+            processFile(linter, themeFile);
+        }
+    });
 
-            if (templateTest) {
-                processFile(linter, themeFile);
-            }
-        });
+    theme.partials = Object.keys(partialsFound);
 
-        theme.partials = Object.keys(partialsFound);
+    // Route each failure to its target rule code (default for parse errors,
+    // missing partials, and missing helpers — they're all GS005-TPL-ERR).
+    // The lint rules attach a `code` field to flag the rule they belong to.
+    const failuresByCode = _.groupBy(failures, f => f.code || DEFAULT_CODE);
 
-        if (failures.length > 0) {
-            theme.results.fail[ruleCode] = {failures: failures};
+    _.each(rulesToCheck, function (rule, ruleCode) {
+        const matchingFailures = (failuresByCode[ruleCode] || []).map(f => _.omit(f, 'code'));
+        if (matchingFailures.length > 0) {
+            theme.results.fail[ruleCode] = {failures: matchingFailures};
         } else {
             theme.results.pass.push(ruleCode);
         }

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

@@ -26,12 +26,12 @@ const ruleImplementations = {
             const config = Object.keys(theme.customSettings);
             const notUsedVariable = config.filter(x => !result.customThemeSettings.has(x));
 
-            if (notUsedVariable.length > 0) {
+            notUsedVariable.forEach((name) => {
                 log.failure({
-                    message: `Found unused variables: ${notUsedVariable.map(x => '@custom.' + x).join(', ')}`,
+                    message: `config.custom.${name} is declared but never referenced from a template`,
                     ref: 'package.json'
                 });
-            }
+            });
         }
     }
 };

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

@@ -1,6 +1,26 @@
 const _ = require('lodash');
+const spec = require('../specs');
+const {versions} = require('../utils');
 const {getRules, applyRule, parseWithAST} = require('../utils/check-utils');
 
+function findPageTemplateRef(theme) {
+    if (!theme || !Array.isArray(theme.files)) {
+        return 'page.hbs';
+    }
+
+    const pageHbs = theme.files.find(f => f.normalizedFile === 'page.hbs');
+    if (pageHbs) {
+        return pageHbs.normalizedFile;
+    }
+
+    const pageOverride = theme.files.find(f => /^page-[^/]+\.hbs$/.test(f.normalizedFile));
+    if (pageOverride) {
+        return pageOverride.normalizedFile;
+    }
+
+    return 'page.hbs';
+}
+
 const ruleImplementations = {
     'GS110-NO-MISSING-PAGE-BUILDER-USAGE': {
         isEnabled: true,
@@ -20,15 +40,21 @@ const ruleImplementations = {
                 }});
             }
         },
-        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'];
+        done: ({theme, log, result, options}) => {
+            const checkVersion = _.get(options, 'checkVersion', versions.default);
+            const knownPageBuilderProperties = spec.get([checkVersion]).pageBuilderProperties || [];
             const notUsedProperties = knownPageBuilderProperties.filter(x => !result.pageBuilderProperties.has(x));
 
+            if (!notUsedProperties.length) {
+                return;
+            }
+
+            const ref = findPageTemplateRef(theme);
+
             notUsedProperties.forEach((property) => {
                 log.failure({
-                    ref: `page.hbs`,
-                    message: `@page.${property} is not used`
+                    ref,
+                    message: `{{@page.${property}}} is not used`
                 });
             });
         }

package/lib/specs/v1.js

@@ -385,6 +385,14 @@ rules = {
         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>.`
     },
+    'GS005-NO-INLINE-DYNAMIC-PARTIAL': {
+        level: 'error',
+        fatal: true,
+        rule: 'Use the block form for dynamic partials',
+        details: oneLineTrim`Inline dynamic partials (e.g. <code>{{> (dynamicPartial)}}</code>) throw a page error if the named partial doesn't exist. Use the block form, which falls back to the inner content when the partial is missing:<br>
+        <code>&#123;&#123;#&gt; (dynamicPartial)&#125;&#125;fallback markup&#123;&#123;/undefined&#125;&#125;</code><br>
+        See the <a href="${docsBaseUrl}helpers/utility/partials/#dynamic-partials" target=_blank>partials documentation</a> for details.`
+    },
     'GS010-PJ-REQ': {
         level: 'error',
         rule: '<code>package.json</code> file should be present',

package/lib/specs/v4.js

@@ -172,9 +172,9 @@ let rules = {
     },
     'GS090-NO-UNKNOWN-CUSTOM-THEME-SETTINGS': {
         level: 'error',
-        rule: 'An unknown custom theme setting has been used.',
         fatal: false,
-        details: oneLineTrim`The custom theme setting should all be defined in the package.json <code>config.custom</code> object.`
+        rule: 'Remove or correct the unknown <code>{{@custom}}</code> setting',
+        details: oneLineTrim`Every <code>{{@custom.<i>name</i>}}</code> reference in a template needs a matching entry in <code>config.custom</code> in <code>package.json</code>. An unrecognised setting renders as empty. See the <a href="${docsBaseUrl}custom-settings/" target=_blank>custom settings documentation</a> for details.`
     },
     'GS090-NO-UNKNOWN-CUSTOM-THEME-SELECT-VALUE-IN-MATCH': {
         level: 'error',
@@ -209,8 +209,8 @@ let rules = {
 
     'GS100-NO-UNUSED-CUSTOM-THEME-SETTING': {
         level: 'error',
-        rule: 'A custom theme setting defined in <code>package.json</code> hasn\'t been used in any theme file.',
-        details: oneLineTrim`Custom theme settings defined in <code>package.json</code> must be used at least once in the theme templates.`
+        rule: 'Use or remove the unused <code>config.custom</code> setting',
+        details: oneLineTrim`A setting declared in <code>config.custom</code> in <code>package.json</code> appears in the admin Customize panel but has no effect unless referenced from a template with <code>{{@custom.<i>name</i>}}</code>. Either use the setting from a template or drop it from <code>package.json</code>. See the <a href="${docsBaseUrl}custom-settings/" target=_blank>custom settings documentation</a> for details.`
     },
 
     'GS050-CSS-KGCO': cssCardRule('callout', 'kg-callout-card'),

package/lib/specs/v5.js

@@ -726,17 +726,14 @@ let rules = {
         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: 'error',
-        rule: 'Not all page features are being used',
-        details: oneLineTrim`<b>This error only applies to pages created with the Beta editor.</b> 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>.`
+        level: 'warning',
+        rule: 'Support the <code>{{@page.show_title_and_feature_image}}</code> editor setting',
+        details: oneLineTrim`Pages have a toggle that lets editors hide a page's title and feature image on a per-page basis. Gate any relevant markup in page templates with <code>{{#if @page.show_title_and_feature_image}}</code> for the toggle to take effect.`
     },
     'GS110-NO-UNKNOWN-PAGE-BUILDER-USAGE': {
-        level: 'error',
-        fatal: true,
-        rule: 'Unsupported page builder feature used',
-        details: oneLineTrim`A page feature used via the <code>{{@page}}</code> global was detected but is not supported by this version of Ghost. Please upgrade to the latest version for full access.&nbsp;
-        You can find more information about the <code>{{@page}}</code> global <a href="${docsBaseUrl}helpers/page/" target=_blank>here</a>.`
+        level: 'warning',
+        rule: 'Remove or correct the unknown <code>{{@page}}</code> property',
+        details: oneLineTrim`Ghost currently supports only <code>{{@page.show_title_and_feature_image}}</code>. Remove the reference or correct the spelling — see the <a href="${docsBaseUrl}helpers/page/" target=_blank><code>{{@page}}</code> documentation</a> for details.`
     },
     'GS120-NO-UNKNOWN-GLOBALS': {
         level: 'error',
@@ -776,6 +773,7 @@ module.exports = {
     knownHelpers: knownHelpers,
     templates: templates,
     rules: rules,
+    pageBuilderProperties: ['show_title_and_feature_image'],
     /**
      * Copy of Ghost defaults for https://github.com/TryGhost/Ghost/blob/e25f1df0ae551c447da0d319bae06eadf9665444/core/frontend/services/theme-engine/config/defaults.json
      */

package/lib/specs/v6.js

@@ -61,5 +61,6 @@ module.exports = {
     knownHelpers: knownHelpers,
     templates: templates,
     rules: rules,
+    pageBuilderProperties: previousSpec.pageBuilderProperties,
     defaultPackageJSON: previousSpec.defaultPackageJSON
 };

package/lib/utils/check-utils.js

@@ -51,19 +51,19 @@ function applyRule(rule, theme) {
 
         // Initialize the rule (optional)
         if (typeof rule.init === 'function') {
-            rule.init({theme, log: getLogger({theme, rule}), result});
+            rule.init({theme, log: getLogger({theme, rule}), result, options: rule.options});
         }
 
         // 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});
+                rule.eachFile({file: themeFile, theme, log: getLogger({theme, rule}), result, partialVerificationCache, options: rule.options});
             });
         }
 
         // Run the final function
         if (typeof rule.done === 'function') {
-            rule.done({theme, log: getLogger({theme, rule}), result});
+            rule.done({theme, log: getLogger({theme, rule}), result, options: rule.options});
         }
     } catch (e) {
         // Output something instead of failing silently (should never happen)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gscan",
-  "version": "6.1.0",
+  "version": "6.2.1",
   "description": "Scans Ghost themes looking for errors, deprecations, features and compatibility",
   "keywords": [
     "ghost",
@@ -43,15 +43,15 @@
     "gscan": "./bin/cli.js"
   },
   "dependencies": {
-    "@sentry/node": "10.52.0",
-    "@tryghost/config": "2.2.0",
-    "@tryghost/debug": "2.2.0",
-    "@tryghost/errors": "3.2.1",
-    "@tryghost/logging": "4.2.1",
+    "@sentry/node": "10.53.1",
+    "@tryghost/config": "2.2.1",
+    "@tryghost/debug": "2.2.1",
+    "@tryghost/errors": "3.2.2",
+    "@tryghost/logging": "5.0.1",
     "@tryghost/nql": "0.12.10",
-    "@tryghost/pretty-cli": "3.2.0",
-    "@tryghost/server": "2.2.1",
-    "@tryghost/zip": "3.3.1",
+    "@tryghost/pretty-cli": "3.2.1",
+    "@tryghost/server": "3.0.1",
+    "@tryghost/zip": "3.3.2",
     "chalk": "5.6.2",
     "express": "5.2.1",
     "express-handlebars": "8.0.1",
@@ -59,24 +59,19 @@
     "handlebars": "4.7.9",
     "lodash": "4.18.1",
     "multer": "2.1.1",
-    "semver": "7.8.0",
+    "semver": "7.8.1",
     "validator": "^13.0.0"
   },
   "devDependencies": {
     "@eslint/compat": "2.1.0",
     "@eslint/eslintrc": "3.3.5",
     "@eslint/js": "10.0.1",
-    "@tryghost/pro-ship": "1.0.8",
-    "@vitest/coverage-v8": "4.1.5",
-    "eslint": "10.3.0",
+    "@tryghost/pro-ship": "1.0.10",
+    "@vitest/coverage-v8": "4.1.7",
+    "eslint": "10.4.0",
     "eslint-plugin-ghost": "3.5.0",
     "nodemon": "3.1.14",
-    "vitest": "4.1.5"
-  },
-  "resolutions": {
-    "node-loggly-bulk": "4.0.2",
-    "node-loggly-bulk/axios": "1.16.0",
-    "**/handlebars": "4.7.9"
+    "vitest": "4.1.7"
   },
   "files": [
     "lib",