Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Theme check for settings keys inside presets and default #742

Merged
merged 2 commits into from
Feb 10, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/forty-moose-pay.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
'@shopify/theme-check-common': minor
'@shopify/theme-check-node': minor
---

Theme check verifies if setting key exists within block schemas and section schemas

- Check if the keys inside `presets.[].settings` and `default.settings` exist as `settings.[].id` in the same file
- Check if the keys inside `presets.[](recursive .blocks.[]).settings` and `default.blocks.[].settings` exist as `settings.[].id` inside the referenced block's file
2 changes: 2 additions & 0 deletions packages/theme-check-common/src/checks/index.ts
Original file line number Diff line number Diff line change
@@ -42,6 +42,7 @@ import { ValidJSON } from './valid-json';
import { ValidLocalBlocks } from './valid-local-blocks';
import { ValidSchema } from './valid-schema';
import { ValidSchemaName } from './valid-schema-name';
import { ValidSettingsKey } from './valid-settings-key';
import { ValidStaticBlockType } from './valid-static-block-type';
import { VariableName } from './variable-name';
import { AppBlockMissingSchema } from './app-block-missing-schema';
@@ -91,6 +92,7 @@ export const allChecks: (LiquidCheckDefinition | JSONCheckDefinition)[] = [
ValidJSON,
ValidLocalBlocks,
ValidSchema,
ValidSettingsKey,
ValidStaticBlockType,
VariableName,
ValidSchemaName,
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
import { expect, describe, it } from 'vitest';
import { ValidBlockTarget } from './index';
import { check, MockTheme } from '../../test';
import { Dependencies } from '../../types';

describe('Module: ValidBlockTarget', () => {
const paths = ['sections', 'blocks'];
Original file line number Diff line number Diff line change
@@ -15,7 +15,7 @@ import {
validateNestedBlocks,
validateBlockFileExistence,
reportWarning,
} from './block-utils';
} from '../../utils';
type BlockNodeWithPath = {
node: Section.Block | ThemeBlock.Block | Preset.Block;
path: string[];
Original file line number Diff line number Diff line change
@@ -0,0 +1,321 @@
import { expect, describe, it } from 'vitest';
import { ValidSettingsKey } from './index';
import { check } from '../../test';

describe('Moduel: ValidSettingsKey', () => {
const schemaTemplate = {
name: 'Example',
settings: [
{
id: 'existent-setting',
type: 'text',
label: 'Example Text Setting',
},
],
};

describe('default settings', () => {
it('does not report an error when default setting exists', async () => {
const theme = {
'sections/example.liquid': toLiquidFile({
...schemaTemplate,
default: {
settings: {
'existent-setting': 'value',
},
},
}),
};

const offenses = await check(theme, [ValidSettingsKey]);
expect(offenses).to.have.length(0);
});

it('reports an error when default setting does not exist', async () => {
const theme = {
'sections/example.liquid': toLiquidFile({
...schemaTemplate,
default: {
settings: {
'non-existent-setting': 'value',
},
},
}),
};

const offenses = await check(theme, [ValidSettingsKey]);
expect(offenses).to.have.length(1);
expect(offenses[0].message).to.equal(
`Setting 'non-existent-setting' does not exist in schema.`,
);
});
Copy link
Contributor

@jamesmengo jamesmengo Feb 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's add a case for n>1 offenses + a case where we have 1 missing 1 valid?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can definitely do 2 missing settings. But checking across multiple rules wouldn't be unit testing this rule.


it('does not report an error when missing default settings is referenced from a block schema', async () => {
const theme = {
'blocks/example.liquid': toLiquidFile({
...schemaTemplate,
default: {
settings: {
'non-existent-setting': 'value',
},
},
}),
};

const offenses = await check(theme, [ValidSettingsKey]);
expect(offenses).to.have.length(0);
});
});

describe('presets settings', () => {
it('does not report an error when presets setting exists', async () => {
const theme = {
'sections/example.liquid': toLiquidFile({
...schemaTemplate,
presets: [
{
settings: {
'existent-setting': 'value',
},
},
],
}),
};

const offenses = await check(theme, [ValidSettingsKey]);
expect(offenses).to.have.length(0);
});

it('reports an error when presets setting does not exist', async () => {
const theme = {
'sections/example.liquid': toLiquidFile({
...schemaTemplate,
presets: [
{
settings: {
'non-existent-setting-1': 'value',
},
},
{
settings: {
'non-existent-setting-2': 'value',
},
},
],
}),
};

const offenses = await check(theme, [ValidSettingsKey]);
expect(offenses).to.have.length(2);
expect(offenses[0].message).to.equal(
`Setting 'non-existent-setting-1' does not exist in schema.`,
);
expect(offenses[1].message).to.equal(
`Setting 'non-existent-setting-2' does not exist in schema.`,
);
});
});

const tests = [
{
label: 'default',
blockTemplate: (blocks: any[]) => {
return {
default: {
blocks,
},
};
},
},
{
label: 'presets',
blockTemplate: (blocks: any[]) => {
return {
presets: [
{
blocks,
},
],
};
},
},
];

tests.forEach(({ label, blockTemplate }) => {
describe(`${label} block settings`, () => {
describe('referenced blocks', () => {
const referencedBlock = {
'blocks/referenced.liquid': toLiquidFile(schemaTemplate),
};

it(`does not report an error when ${label} block setting exists in referenced file`, async () => {
const fileToTest = {
'sections/example.liquid': toLiquidFile({
...schemaTemplate,
...blockTemplate([
{
type: 'referenced',
settings: {
'existent-setting': 'value',
},
},
]),
}),
};

const offenses = await check(
{
...referencedBlock,
...fileToTest,
},
[ValidSettingsKey],
);
expect(offenses).to.have.length(0);
});

it('does not report an error when referenced file does not exist', async () => {
const fileToTest = {
'sections/example.liquid': toLiquidFile({
...schemaTemplate,
...blockTemplate([
{
type: 'non-existent-file',
settings: {
'non-existent-setting': 'value',
},
},
]),
}),
};

const offenses = await check(
{
...referencedBlock,
...fileToTest,
},
[ValidSettingsKey],
);
expect(offenses).to.have.length(0);
});

it(`reports an error when ${label} block setting does not exist in referenced file`, async () => {
const fileToTest = {
'sections/example.liquid': toLiquidFile({
...schemaTemplate,
...blockTemplate([
{
type: 'referenced',
settings: {
'non-existent-setting': 'value',
},
},
]),
}),
};

const offenses = await check(
{
...referencedBlock,
...fileToTest,
},
[ValidSettingsKey],
);
expect(offenses).to.have.length(1);
expect(offenses[0].message).to.equal(
`Setting 'non-existent-setting' does not exist in 'blocks/referenced.liquid'.`,
);
});
});

describe('local blocks', () => {
const localBlocksTemplate = {
blocks: [
{
type: 'local-block',
name: 'Local block',
settings: [
{
id: 'local-setting',
type: 'text',
label: 'Local Setting',
},
],
},
],
};

it(`reports an error when ${label} block setting does not exist in existing local block`, async () => {
const fileToTest = {
'sections/example.liquid': toLiquidFile({
...localBlocksTemplate,
...blockTemplate([
{
type: 'local-block',
settings: {
'non-existent-setting-1': 'value',
'non-existent-setting-2': 'value',
},
},
]),
}),
};

const offenses = await check(fileToTest, [ValidSettingsKey]);
expect(offenses).to.have.length(2);
expect(offenses[0].message).to.equal(
`Setting 'non-existent-setting-1' does not exist in schema.`,
);
expect(offenses[1].message).to.equal(
`Setting 'non-existent-setting-2' does not exist in schema.`,
);
});

it(`does not report an error when ${label} block setting does not exist in non-existent local block`, async () => {
const fileToTest = {
'sections/example.liquid': toLiquidFile({
...localBlocksTemplate,
...blockTemplate([
{
type: 'non-existent-local-block',
settings: {
'non-existent-setting': 'value',
},
},
]),
}),
};

const offenses = await check(fileToTest, [ValidSettingsKey]);
expect(offenses).to.have.length(0);
});

it(`does not report an error when ${label} block setting exists in local block`, async () => {
const fileToTest = {
'sections/example.liquid': toLiquidFile({
...localBlocksTemplate,
...blockTemplate([
{
type: 'local-block',
settings: {
'local-setting': 'value',
},
},
]),
}),
};

const offenses = await check(fileToTest, [ValidSettingsKey]);
expect(offenses).to.have.length(0);
});
});
});
});
});

function toLiquidFile(content: any) {
return `
{% schema %}
${JSON.stringify(content)}
{% endschema %}
`;
}
129 changes: 129 additions & 0 deletions packages/theme-check-common/src/checks/valid-settings-key/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
import {
LiquidCheckDefinition,
Severity,
SourceCodeType,
Preset,
Section,
ThemeBlock,
JSONNode,
Setting,
} from '../../types';
import { nodeAtPath } from '../../json';
import { getSchema, isSectionSchema } from '../../to-schema';
import { BlockNodeWithPath, getBlocks, reportWarning } from '../../utils';

export const ValidSettingsKey: LiquidCheckDefinition = {
meta: {
code: 'ValidSettingsKey',
name: 'Validate settings key in presets',
docs: {
description:
"Ensures settings key only references valid settings defined in it's respective schema",
recommended: true,
url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-settings-key',
},
type: SourceCodeType.LiquidHtml,
severity: Severity.ERROR,
schema: {},
targets: [],
},

create(context) {
return {
async LiquidRawTag(node) {
if (node.name !== 'schema' || node.body.kind !== 'json') return;

const offset = node.blockStartPosition.end;
const schema = await getSchema(context);

const { validSchema, ast } = schema ?? {};
if (!validSchema || validSchema instanceof Error) return;
if (!ast || ast instanceof Error) return;

const { rootLevelLocalBlocks, presetLevelBlocks } = getBlocks(validSchema);

// Check if presets settings match schema-level settings
if (validSchema.presets) {
for (let i = 0; i < validSchema.presets.length; i++) {
const settingsNode = nodeAtPath(ast, ['presets', i, 'settings']);

validateSettingsKey(context, offset, settingsNode, validSchema.settings);
}
}

if (isSectionSchema(schema) && 'default' in validSchema && validSchema.default) {
// Check if default settings match schema-level settings
const settingsNode = nodeAtPath(ast, ['default', 'settings']);

validateSettingsKey(context, offset, settingsNode, validSchema.settings);

// Check if default block settings match the settings defined in the block file's schema
validSchema.default.blocks?.forEach(async (block, i) => {
const settingsNode = nodeAtPath(ast, ['default', 'blocks', i, 'settings']);

validateReferencedBlock(context, offset, settingsNode, rootLevelLocalBlocks, block);
});
}

// Check if preset block settings match the settings defined in the block file's schema
for (let [_depthStr, blocks] of Object.entries(presetLevelBlocks)) {
blocks.forEach(async ({ node: blockNode, path }) => {
const settingsNode = nodeAtPath(ast, path.slice(0, -1).concat('settings'));

validateReferencedBlock(context, offset, settingsNode, rootLevelLocalBlocks, blockNode);
});
}
},
};
},
};

async function validateReferencedBlock(
context: any,
offset: number,
settingsNode: JSONNode | undefined,
localBlocks: BlockNodeWithPath[],
referencedBlock: Preset.Block | Section.Block | ThemeBlock.Block,
) {
if (localBlocks.length > 0) {
const localBlock = localBlocks.find(
(localBlock) => localBlock.node.type === referencedBlock.type,
);

if (!localBlock) return;

const localBlockNode = localBlock.node as Section.LocalBlock;

validateSettingsKey(context, offset, settingsNode, localBlockNode.settings);
} else {
const blockSchema = await context.getBlockSchema?.(referencedBlock.type);
const { validSchema: validBlockSchema } = blockSchema ?? {};
if (!validBlockSchema || validBlockSchema instanceof Error) return;

validateSettingsKey(context, offset, settingsNode, validBlockSchema.settings, referencedBlock);
}
}

function validateSettingsKey(
context: any,
offset: number,
settingsNode: JSONNode | undefined,
validSettings: Setting.Any[] | undefined,
blockNode?: Section.Block | ThemeBlock.Block | Preset.Block,
) {
if (!settingsNode || settingsNode.type !== 'Object') return;

for (const setting of settingsNode.children) {
const settingExists = validSettings?.find(
(validSetting) => validSetting?.id === setting.key.value,
);

if (!settingExists) {
const errorMessage = blockNode
? `Setting '${setting.key.value}' does not exist in 'blocks/${blockNode.type}.liquid'.`
: `Setting '${setting.key.value}' does not exist in schema.`;

reportWarning(errorMessage, offset, setting.key, context);
}
}
}
Original file line number Diff line number Diff line change
@@ -1,15 +1,7 @@
import {
JSONNode,
LiteralNode,
Preset,
Section,
SourceCodeType,
Theme,
ThemeBlock,
} from '../../types';
import { getLocEnd, getLocStart, nodeAtPath } from '../../json';
import { Context } from '../../types';
import { doesFileExist } from '../../utils/file-utils';
import { JSONNode, LiteralNode, Preset, Section, SourceCodeType, ThemeBlock } from '../types';
import { getLocEnd, getLocStart, nodeAtPath } from '../json';
import { Context } from '../types';
import { doesFileExist } from './file-utils';

export type BlockNodeWithPath = {
node: Section.Block | ThemeBlock.Block | Preset.Block;
@@ -213,7 +205,7 @@ export async function validateNestedBlocks(
export function reportWarning(
message: string,
offset: number,
astNode: LiteralNode,
astNode: JSONNode,
context: Context<SourceCodeType.LiquidHtml>,
) {
context.report({
1 change: 1 addition & 0 deletions packages/theme-check-common/src/utils/index.ts
Original file line number Diff line number Diff line change
@@ -5,3 +5,4 @@ export * from './error';
export * from './types';
export * from './memo';
export * from './indexBy';
export * from './block';
3 changes: 3 additions & 0 deletions packages/theme-check-node/configs/all.yml
Original file line number Diff line number Diff line change
@@ -142,6 +142,9 @@ ValidSchema:
ValidSchemaName:
enabled: true
severity: 0
ValidSettingsKey:
enabled: true
severity: 0
ValidStaticBlockType:
enabled: true
severity: 0
3 changes: 3 additions & 0 deletions packages/theme-check-node/configs/recommended.yml
Original file line number Diff line number Diff line change
@@ -120,6 +120,9 @@ ValidSchema:
ValidSchemaName:
enabled: true
severity: 0
ValidSettingsKey:
enabled: true
severity: 0
ValidStaticBlockType:
enabled: true
severity: 0