gscan 6.0.2 → 6.2.0

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-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/checker.js

@@ -32,6 +32,7 @@ function loadChecks() {
  * @param {string} [options.themeName] name of the checked theme
  * @param {Object=} [options.labs] object containing boolean flags for enabled labs features
  * @param {boolean} [options.skipChecks] flag to allow reading theme without incurring check costs
+ * @param {Object=} [options.limits] zip extraction size limits
  * @returns {Promise<Object>}
  */
 const check = async function checkAll(themePath, options = {}) {
@@ -105,7 +106,7 @@ const checkZip = async function checkZip(path, options) {
 
     try {
         const readZip = require('./read-zip');
-        ({path: extractedZipPath} = await readZip(zip));
+        ({path: extractedZipPath} = await readZip(zip, {limits: options.limits}));
         return await check(extractedZipPath, Object.assign({themeName: zip.name}, options));
     } catch (error) {
         if (!errors.utils.isGhostError(error)) {

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/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/read-theme.js

@@ -11,6 +11,9 @@ const ignore = [
     '.DS_Store',
     '.git',
     '.svn',
+    '.claude',
+    'CLAUDE.md',
+    'AGENTS.md',
     'Thumbs.db',
     '.yarn-cache'
 ];

package/lib/read-zip.js

@@ -7,6 +7,10 @@ const {extract} = require('@tryghost/zip');
 const errors = require('@tryghost/errors');
 const _ = require('lodash');
 
+const isKnownZipError = (err) => {
+    return errors.utils.isGhostError(err);
+};
+
 const resolveBaseDir = async (zipPath) => {
     let matches = [];
 
@@ -25,12 +29,17 @@ const resolveBaseDir = async (zipPath) => {
     return zipPath;
 };
 
-const readZip = (zip) => {
+const readZip = (zip, options = {}) => {
     const tempUuid = randomUUID();
     const tempPath = os.tmpdir() + '/' + tempUuid;
+    const extractOptions = {};
+
+    if (options.limits) {
+        extractOptions.limits = options.limits;
+    }
 
     debug('Reading Zip', zip.path, 'into', tempPath);
-    return extract(zip.path, tempPath)
+    return extract(zip.path, tempPath, extractOptions)
         .then(async () => {
             let resolvedPath = await resolveBaseDir(tempPath);
             zip.origPath = tempPath;
@@ -41,6 +50,10 @@ const readZip = (zip) => {
         }).catch((err) => {
             debug('Zip extraction error', err);
 
+            if (isKnownZipError(err)) {
+                throw err;
+            }
+
             throw new errors.ValidationError({
                 message: 'Failed to read zip file',
                 help: 'Your zip file might be corrupted, try unzipping and zipping again.',

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/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.0.2",
+  "version": "6.2.0",
   "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",
+    "@sentry/node": "10.53.1",
     "@tryghost/config": "2.2.0",
     "@tryghost/debug": "2.2.0",
-    "@tryghost/errors": "3.2.0",
-    "@tryghost/logging": "4.2.0",
+    "@tryghost/errors": "3.2.1",
+    "@tryghost/logging": "4.2.1",
     "@tryghost/nql": "0.12.10",
     "@tryghost/pretty-cli": "3.2.0",
-    "@tryghost/server": "2.2.0",
-    "@tryghost/zip": "3.2.0",
+    "@tryghost/server": "2.2.1",
+    "@tryghost/zip": "3.3.1",
     "chalk": "5.6.2",
     "express": "5.2.1",
     "express-handlebars": "8.0.1",
@@ -66,16 +66,16 @@
     "@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.6",
+    "eslint": "10.4.0",
     "eslint-plugin-ghost": "3.5.0",
     "nodemon": "3.1.14",
-    "vitest": "4.1.5"
+    "vitest": "4.1.6"
   },
   "resolutions": {
     "node-loggly-bulk": "4.0.2",
-    "node-loggly-bulk/axios": "1.15.2",
+    "node-loggly-bulk/axios": "1.16.0",
     "**/handlebars": "4.7.9"
   },
   "files": [