gscan 6.2.0 → 6.3.0

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/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/130-template-inheritance.js

@@ -0,0 +1,154 @@
+const _ = require('lodash');
+const path = require('path');
+const spec = require('../specs');
+const {versions, normalizePath} = require('../utils');
+
+const ruleCode = 'GS130-NO-RECURSIVE-LAYOUT';
+const layoutPattern = /{{!<\s+([A-Za-z0-9._/-]+)\s*}}/;
+
+function ensureExtension(layoutPath) {
+    if (path.posix.extname(layoutPath)) {
+        return layoutPath;
+    }
+
+    return `${layoutPath}.hbs`;
+}
+
+function resolveLayoutPath(sourceFile, layoutName) {
+    const source = normalizePath(sourceFile);
+    const layout = ensureExtension(normalizePath(layoutName));
+
+    // Ghost resolves layouts with path.resolve(templateDir, layout), so a leading
+    // slash is filesystem-absolute and never resolves to a theme file
+    if (layout.startsWith('/')) {
+        return null;
+    }
+
+    return path.posix.normalize(path.posix.join(path.posix.dirname(source), layout));
+}
+
+function getLocation(source, index) {
+    const lines = source.slice(0, index).split('\n');
+
+    return {
+        line: lines.length,
+        column: lines[lines.length - 1].length
+    };
+}
+
+function getLayoutReference(themeFile) {
+    const source = normalizePath(themeFile.normalizedFile || themeFile.file);
+    const content = themeFile.content || '';
+    const match = content.match(layoutPattern);
+
+    if (!match) {
+        return;
+    }
+
+    const target = resolveLayoutPath(source, match[1]);
+
+    if (!target) {
+        return;
+    }
+
+    return {
+        source,
+        target,
+        location: getLocation(content, match.index)
+    };
+}
+
+function buildInheritanceGraph(theme) {
+    const hbsFiles = theme.files.filter(file => file.ext === '.hbs');
+    const existingFiles = new Set(hbsFiles.map(file => normalizePath(file.normalizedFile || file.file)));
+    const graph = new Map();
+
+    hbsFiles.forEach((themeFile) => {
+        const reference = getLayoutReference(themeFile);
+
+        if (!reference || !existingFiles.has(reference.target)) {
+            return;
+        }
+
+        graph.set(reference.source, reference);
+    });
+
+    return graph;
+}
+
+function getCyclePath(stack, target) {
+    const targetIndex = stack.indexOf(target);
+    return stack.slice(targetIndex).concat(target).join(' -> ');
+}
+
+function getRecursiveLayoutFailures(graph) {
+    const visited = new Set();
+    const visiting = new Set();
+    const stack = [];
+    const reportedCycles = new Set();
+    const failures = [];
+
+    function visit(file) {
+        visiting.add(file);
+        stack.push(file);
+
+        const reference = graph.get(file);
+
+        if (!reference) {
+            stack.pop();
+            visiting.delete(file);
+            visited.add(file);
+            return;
+        }
+
+        if (visiting.has(reference.target)) {
+            const cyclePath = getCyclePath(stack, reference.target);
+
+            if (!reportedCycles.has(cyclePath)) {
+                reportedCycles.add(cyclePath);
+
+                failures.push({
+                    ref: reference.source,
+                    line: reference.location.line,
+                    column: reference.location.column,
+                    message: `Recursive layout inheritance detected: ${cyclePath}`
+                });
+            }
+        } else if (!visited.has(reference.target)) {
+            visit(reference.target);
+        }
+
+        stack.pop();
+        visiting.delete(file);
+        visited.add(file);
+    }
+
+    graph.forEach((_references, file) => {
+        if (!visited.has(file)) {
+            visit(file);
+        }
+    });
+
+    return failures;
+}
+
+const checkTemplateInheritance = function checkTemplateInheritance(theme, options) {
+    const checkVersion = _.get(options, 'checkVersion', versions.default);
+    const ruleSet = spec.get([checkVersion]);
+
+    if (!ruleSet.rules[ruleCode]) {
+        return theme;
+    }
+
+    const failures = getRecursiveLayoutFailures(buildInheritanceGraph(theme));
+
+    if (failures.length > 0) {
+        theme.results.fail[ruleCode] = {failures};
+    } else {
+        theme.results.pass.push(ruleCode);
+    }
+
+    return theme;
+};
+
+module.exports = checkTemplateInheritance;

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

@@ -48,6 +48,12 @@ let rules = {
         details: 'AMP support was removed in Ghost 6.0. Remove AMP templates and use responsive design instead.',
         // Matches <html amp> or <html ⚡>, with or without other attributes mixed in
         regex: /<html\s+(?:amp|⚡)(?:\s|>)|<html\s+[^>]*\s(?:amp|⚡)(?:\s|>)/i
+    },
+    'GS130-NO-RECURSIVE-LAYOUT': {
+        level: 'error',
+        fatal: true,
+        rule: 'Templates must not recursively inherit layouts',
+        details: oneLineTrim`Remove recursive layout inheritance such as <code>{{!&lt; default}}</code> from <code>default.hbs</code>. A template cannot inherit from itself, directly or through another layout, because it can cause rendering to recurse indefinitely.`
     }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gscan",
-  "version": "6.2.0",
+  "version": "6.3.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.53.1",
-    "@tryghost/config": "2.2.0",
-    "@tryghost/debug": "2.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.1",
-    "@tryghost/zip": "3.3.1",
+    "@sentry/node": "10.56.0",
+    "@tryghost/config": "2.2.2",
+    "@tryghost/debug": "2.2.2",
+    "@tryghost/errors": "3.2.3",
+    "@tryghost/logging": "5.0.2",
+    "@tryghost/nql": "0.12.11",
+    "@tryghost/pretty-cli": "3.2.2",
+    "@tryghost/server": "3.0.2",
+    "@tryghost/zip": "3.3.3",
     "chalk": "5.6.2",
     "express": "5.2.1",
     "express-handlebars": "8.0.1",
@@ -59,7 +59,7 @@
     "handlebars": "4.7.9",
     "lodash": "4.18.1",
     "multer": "2.1.1",
-    "semver": "7.8.0",
+    "semver": "7.8.2",
     "validator": "^13.0.0"
   },
   "devDependencies": {
@@ -67,16 +67,11 @@
     "@eslint/eslintrc": "3.3.5",
     "@eslint/js": "10.0.1",
     "@tryghost/pro-ship": "1.0.10",
-    "@vitest/coverage-v8": "4.1.6",
-    "eslint": "10.4.0",
+    "@vitest/coverage-v8": "4.1.8",
+    "eslint": "10.4.1",
     "eslint-plugin-ghost": "3.5.0",
     "nodemon": "3.1.14",
-    "vitest": "4.1.6"
-  },
-  "resolutions": {
-    "node-loggly-bulk": "4.0.2",
-    "node-loggly-bulk/axios": "1.16.0",
-    "**/handlebars": "4.7.9"
+    "vitest": "4.1.8"
   },
   "files": [
     "lib",