{{ product.title }}' +
+ "{% if product.available %}{{ product.price }}{% endif %}" +
+ "
\n";
+
+export const ERROR_FILES: Array<{ path: string; source: string }> = [
+ {
+ /* Seeded verbatim from tolerant.test.ts:150 — one orphan close tag. */
+ path: "error-corpus/single-error.liquid",
+ source: "{% endfor %}",
+ },
+ {
+ /*
+ * Seeded verbatim from tolerant.test.ts:178 — two orphan closes with a
+ * valid output recovered between them (interleaved resync).
+ */
+ path: "error-corpus/interleaved-resync.liquid",
+ source: "{% endfor %}{{ good }}{% endif %}",
+ },
+ {
+ /*
+ * Net-new: an orphan close roughly every few tokens across a moderately
+ * long source, bounding worst-case resync frequency.
+ *
+ * 60 units yields 120 error nodes interleaved with 120 recovered
+ * outputs.
+ */
+ path: "error-corpus/pathological-frequent.liquid",
+ source: FREQUENT_ERROR_UNIT.repeat(60),
+ },
+ {
+ /*
+ * Net-new: a large valid body (150 clean units) with a single orphan
+ * close tag just before EOF — "parse a lot, then recover once".
+ */
+ path: "error-corpus/large-clean-error-near-eof.liquid",
+ source: CLEAN_UNIT.repeat(150) + "{% endfor %}",
+ },
+];
diff --git a/packages/liquid-html-parser/package.json b/packages/liquid-html-parser/package.json
index e052b1b57..aba6395a9 100644
--- a/packages/liquid-html-parser/package.json
+++ b/packages/liquid-html-parser/package.json
@@ -20,7 +20,6 @@
"@shopify:registry": "https://registry.npmjs.org"
},
"files": [
- "grammar/*",
"dist/**/*.js",
"dist/**/*.ts"
],
@@ -28,11 +27,11 @@
"build": "pnpm build:ts",
"build:ci": "pnpm build",
"build:ts": "tsc -p tsconfig.build.json",
- "type-check": "tsc --noEmit"
+ "type-check": "tsc --noEmit",
+ "test": "vitest --root ../.. --run src/**/*.test.ts"
},
"dependencies": {
- "line-column": "^1.0.2",
- "ohm-js": "^17.0.0"
+ "line-column": "^1.0.2"
},
"devDependencies": {
"@types/line-column": "^1.0.0",
diff --git a/packages/liquid-html-parser/src/ast.test.ts b/packages/liquid-html-parser/src/ast.test.ts
index 3fc517c4b..996d97a6d 100644
--- a/packages/liquid-html-parser/src/ast.test.ts
+++ b/packages/liquid-html-parser/src/ast.test.ts
@@ -1345,6 +1345,26 @@ describe('Unit: Stage 2 (AST)', () => {
expect(useChild.type).to.eql('TextNode');
});
+ it('should depth-balance nested same-name raw tags and close at the outer tag (issue 156)', () => {
+ const expectPath = makeExpectPath('toLiquidHtmlAST - nested raw close balancing');
+
+ // Nested (which previously threw / mis-parsed).
+ ast = toLiquidHtmlAST('');
+ expectPath(ast, 'children').to.have.lengthOf(1);
+ expectPath(ast, 'children.0.type').to.eql('HtmlRawNode');
+ expectPath(ast, 'children.0.name').to.eql('svg');
+ expectPath(ast, 'children.0.body.value').to.eql('ac');
+
+ // Same balancing for a non-svg raw tag (c');
+ expectPath(ast, 'children').to.have.lengthOf(1);
+ expectPath(ast, 'children.0.type').to.eql('HtmlRawNode');
+ expectPath(ast, 'children.0.name').to.eql('script');
+ expectPath(ast, 'children.0.body.value').to.eql('ac');
+ });
+
it(`should parse a basic text node into a TextNode`, () => {
for (const { toAST, expectPath, expectPosition } of testCases) {
ast = toAST('Hello world!');
diff --git a/packages/liquid-html-parser/src/ast.ts b/packages/liquid-html-parser/src/ast.ts
index d95c2df13..cc1051e66 100644
--- a/packages/liquid-html-parser/src/ast.ts
+++ b/packages/liquid-html-parser/src/ast.ts
@@ -49,7 +49,8 @@ export type LiquidHtmlNode =
| LiquidDocParamNode
| LiquidDocExampleNode
| LiquidDocPromptNode
- | LiquidDocDescriptionNode;
+ | LiquidDocDescriptionNode
+ | LiquidErrorNode;
/** The root node of all LiquidHTML ASTs. */
export interface DocumentNode extends ASTNode{{ x }}
',
+ '{% render \'snippet\' %}',
+ '{% liquid\n assign y = 2\n echo y\n%}',
+ '{% comment %}hi{% endcomment %}',
+ 'text {{ a }} more {% if b %}{{ c }}{% endif %} end',
+ ];
+
+ for (const source of cleanSources) {
+ it(`toTolerantLiquidHtmlAST deep-equals toLiquidHtmlAST for ${JSON.stringify(source)}`, () => {
+ expect(structural(toTolerantLiquidHtmlAST(source))).toEqual(
+ structural(toLiquidHtmlAST(source)),
+ );
+ });
+
+ it(`toTolerantLiquidAST deep-equals toLiquidAST for ${JSON.stringify(source)}`, () => {
+ expect(structural(toTolerantLiquidAST(source))).toEqual(structural(toLiquidAST(source)));
+ });
+ }
+});
+
+const FIXTURES_DIR = resolve(__dirname, '..', 'fixtures', 'theme');
+const GOLDEN_HTML_AST_DIR = resolve(__dirname, '..', 'fixtures', 'golden-html-ast');
+const GOLDEN_LIQUID_AST_DIR = resolve(__dirname, '..', 'fixtures', 'golden-liquid-ast');
+const THEMES = ['base-theme', 'dawn', 'horizon'];
+
+/** Recursively find all .liquid files under a directory. */
+function findLiquidFiles(dir: string, prefix = ''): { path: string; fullPath: string }[] {
+ const results: { path: string; fullPath: string }[] = [];
+ if (!existsSync(dir)) return results;
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+ if (entry.isDirectory()) {
+ results.push(...findLiquidFiles(join(dir, entry.name), relPath));
+ } else if (entry.name.endsWith('.liquid')) {
+ results.push({ path: relPath, fullPath: join(dir, entry.name) });
+ }
+ }
+ return results;
+}
+
+function goldenFileName(relativePath: string): string {
+ return relativePath.replace(/\//g, '-') + '.json';
+}
+
+const hasFixtures = existsSync(FIXTURES_DIR) && readdirSync(FIXTURES_DIR).length > 0;
+
+/*
+ * The clean corpus is exactly the files the oracle has a golden for: a golden
+ * exists only for a file the strict parser accepts, so those files are the
+ * proven-clean set. Tolerant must reproduce the strict AST for each.
+ */
+describe.skipIf(!hasFixtures)('tolerant mode is inert over the clean fixture corpus', () => {
+ for (const theme of THEMES) {
+ const themeDir = join(FIXTURES_DIR, theme);
+ const files = findLiquidFiles(themeDir);
+ const themeMissing = files.length === 0;
+
+ describe.skipIf(themeMissing)(`toTolerantLiquidHtmlAST === toLiquidHtmlAST - ${theme}`, () => {
+ for (const { path, fullPath } of files) {
+ const goldenPath = join(GOLDEN_HTML_AST_DIR, theme, goldenFileName(path));
+ if (!existsSync(goldenPath)) continue;
+
+ it(`matches strict for ${theme}/${path}`, () => {
+ const source = readFileSync(fullPath, 'utf-8');
+ expect(structural(toTolerantLiquidHtmlAST(source))).toEqual(
+ structural(toLiquidHtmlAST(source)),
+ );
+ });
+ }
+ });
+
+ describe.skipIf(themeMissing)(`toTolerantLiquidAST === toLiquidAST - ${theme}`, () => {
+ for (const { path, fullPath } of files) {
+ const goldenPath = join(GOLDEN_LIQUID_AST_DIR, theme, goldenFileName(path));
+ if (!existsSync(goldenPath)) continue;
+
+ it(`matches strict for ${theme}/${path}`, () => {
+ const source = readFileSync(fullPath, 'utf-8');
+ expect(structural(toTolerantLiquidAST(source))).toEqual(structural(toLiquidAST(source)));
+ });
+ }
+ });
+ }
+});
+
+/*
+ * Positive-path tolerant behavior. These consolidate the throwaway probes
+ * from B2 (error nodes emitted), B3 (panic-mode resync) and B5 (locator) into
+ * committed tests.
+ */
+describe('tolerant mode surfaces parse errors as nodes', () => {
+ it('strict parse throws on a close tag with no matching open', () => {
+ expect(() => toLiquidHtmlAST('{% endfor %}')).toThrow(LiquidHTMLASTParsingError);
+ });
+
+ it('toTolerantLiquidHtmlAST emits a LiquidErrorNode instead of throwing', () => {
+ const source = '{% endfor %}';
+ const ast = toTolerantLiquidHtmlAST(source);
+
+ expect(ast.type).toBe(NodeTypes.Document);
+ expect(ast.children).toHaveLength(1);
+
+ const node = ast.children[0] as LiquidErrorNode;
+ expect(node.type).toBe(NodeTypes.LiquidErrorNode);
+ expect(node.position).toEqual({ start: 0, end: 12 });
+ expect(node.found).toBe('EndOfInput');
+ expect(typeof node.message).toBe('string');
+ expect(source.slice(node.position.start, node.position.end)).toBe('{% endfor %}');
+ });
+
+ it('toTolerantLiquidAST also recovers instead of throwing', () => {
+ const ast = toTolerantLiquidAST('{% endfor %}');
+
+ expect(ast.type).toBe(NodeTypes.Document);
+ expect(errorNodesOf(ast)).toHaveLength(1);
+ });
+});
+
+describe('tolerant mode resynchronizes after an error (panic mode)', () => {
+ it('recovers valid nodes between multiple errors and terminates', () => {
+ const ast = toTolerantLiquidHtmlAST('{% endfor %}{{ good }}{% endif %}');
+
+ expect(ast.children.map((child) => child.type)).toEqual([
+ NodeTypes.LiquidErrorNode,
+ NodeTypes.LiquidVariableOutput,
+ NodeTypes.LiquidErrorNode,
+ ]);
+
+ const errors = errorNodesOf(ast);
+ expect(errors.length).toBeGreaterThanOrEqual(2);
+
+ // The construct between the two errors is recovered as a real node.
+ const recovered = ast.children[1];
+ expect(recovered.type).toBe(NodeTypes.LiquidVariableOutput);
+ expect(recovered.position).toEqual({ start: 12, end: 22 });
+
+ // Errors resynced on the next construct-open boundary.
+ expect(ast.children[0].position).toEqual({ start: 0, end: 12 });
+ expect(ast.children[2].position).toEqual({ start: 22, end: 33 });
+ });
+});
+
+describe('findErrorNodeAtOffset', () => {
+ const source = '{% endfor %} {{ good }} {% endif %}';
+ const ast = toTolerantLiquidHtmlAST(source);
+
+ it('produces two error nodes spanning up to the next construct boundary', () => {
+ const errors = errorNodesOf(ast);
+ expect(errors).toHaveLength(2);
+ expect(errors[0].position).toEqual({ start: 0, end: 13 });
+ expect(errors[1].position).toEqual({ start: 24, end: 35 });
+ });
+
+ it('error nodes are first-class, walkable citizens', () => {
+ const errors = errorNodesOf(ast);
+ expect(isLiquidHtmlNode(errors[0])).toBe(true);
+ });
+
+ it('returns the error node the offset sits inside, with its ancestry', () => {
+ const result = findErrorNodeAtOffset(ast, 5);
+ expect(result).not.toBeNull();
+ expect(result!.node.type).toBe(NodeTypes.LiquidErrorNode);
+ expect(result!.node.position).toEqual({ start: 0, end: 13 });
+ expect(result!.ancestors[0].type).toBe(NodeTypes.Document);
+ });
+
+ it('resolves the second error span for an offset inside it', () => {
+ const result = findErrorNodeAtOffset(ast, 30);
+ expect(result).not.toBeNull();
+ expect(result!.node.position).toEqual({ start: 24, end: 35 });
+ });
+
+ it('returns null for an offset outside every error span', () => {
+ // Offset 17 is inside the recovered {{ good }}, not an error region.
+ expect(findErrorNodeAtOffset(ast, 17)).toBeNull();
+ });
+
+ it('returns the deepest error node when spans nest', () => {
+ const src = 'x'.repeat(20);
+ const inner = {
+ type: NodeTypes.LiquidErrorNode,
+ position: { start: 5, end: 10 },
+ source: src,
+ message: 'inner',
+ } as LiquidErrorNode;
+ const container = {
+ type: NodeTypes.HtmlElement,
+ position: { start: 2, end: 15 },
+ source: src,
+ children: [inner],
+ } as unknown as LiquidHtmlNode;
+ const outer = {
+ type: NodeTypes.LiquidErrorNode,
+ position: { start: 0, end: 20 },
+ source: src,
+ message: 'outer',
+ } as LiquidErrorNode;
+ const root = {
+ type: NodeTypes.Document,
+ name: '#document',
+ position: { start: 0, end: 20 },
+ source: src,
+ _source: src,
+ children: [outer, container],
+ } as unknown as LiquidHtmlNode;
+
+ const deep = findErrorNodeAtOffset(root, 7);
+ expect(deep!.node.message).toBe('inner');
+ expect(deep!.ancestors.map((node) => node.type)).toEqual([
+ NodeTypes.Document,
+ NodeTypes.HtmlElement,
+ ]);
+
+ const shallow = findErrorNodeAtOffset(root, 1);
+ expect(shallow!.node.message).toBe('outer');
+ expect(shallow!.ancestors.map((node) => node.type)).toEqual([NodeTypes.Document]);
+ });
+});
diff --git a/packages/liquid-html-parser/src/tolerant.ts b/packages/liquid-html-parser/src/tolerant.ts
new file mode 100644
index 000000000..27de69e64
--- /dev/null
+++ b/packages/liquid-html-parser/src/tolerant.ts
@@ -0,0 +1,138 @@
+/**
+ * Opt-in tolerant entry points for the Liquid+HTML parser.
+ *
+ * These mirror `toLiquidAST` / `toLiquidHtmlAST` from `./ast` exactly, except
+ * they construct a `TolerantDocumentParser` instead of the base
+ * `DocumentParser`. A structural parse failure that would abort the default
+ * parse is instead caught and surfaced as a `LiquidErrorNode`, so the returned
+ * `DocumentNode` can carry several errors interleaved with the constructs the
+ * parser did recover. The default path is a different class reached by a
+ * different function and stays byte-identical.
+ */
+
+import type { ASTBuildOptions, DocumentNode, LiquidErrorNode, LiquidHtmlNode } from './ast';
+import { walk } from './ast';
+import { TolerantDocumentParser } from './document/tolerant-parser';
+import { tokenize } from './document/tokenizer';
+import { Environment } from './environment';
+import { NodeTypes } from './types';
+
+/*
+ * Tolerant variant of `toLiquidAST` (Liquid-only, `parseHtml: false`).
+ * Defaults `allowUnclosedDocumentNode: true` so an unterminated document is
+ * recovered rather than thrown on — the tolerant contract.
+ */
+export function toTolerantLiquidAST(
+ source: string,
+ options: ASTBuildOptions = {
+ allowUnclosedDocumentNode: true,
+ mode: 'tolerant',
+ },
+): DocumentNode {
+ const env = options.environment ?? Environment.default();
+ const tokens = tokenize(source);
+ const parser = new TolerantDocumentParser(
+ tokens,
+ source,
+ env,
+ false,
+ options.allowUnclosedDocumentNode,
+ );
+ return parser.parseDocument();
+}
+
+/*
+ * Tolerant variant of `toLiquidHtmlAST` (Liquid+HTML, `parseHtml: true`).
+ * Defaults `allowUnclosedDocumentNode: true` so an unterminated document is
+ * recovered rather than thrown on — the tolerant contract.
+ */
+export function toTolerantLiquidHtmlAST(
+ source: string,
+ options: ASTBuildOptions = {
+ allowUnclosedDocumentNode: true,
+ mode: 'tolerant',
+ },
+): DocumentNode {
+ const env = options.environment ?? Environment.default();
+ const tokens = tokenize(source);
+ const parser = new TolerantDocumentParser(
+ tokens,
+ source,
+ env,
+ true,
+ options.allowUnclosedDocumentNode,
+ );
+ return parser.parseDocument();
+}
+
+/*
+ * Locate the error node the caret is sitting in.
+ *
+ * A tolerant parse can leave several `LiquidErrorNode`s scattered through
+ * the tree, one per region the parser gave up on. Completion needs the one
+ * the caret is actually inside, so we return the *deepest* error node whose
+ * span contains `offset` — the most specific recovery point — paired with
+ * its ancestry.
+ *
+ * The result shape (`{ node, ancestors }`) mirrors `findCurrentNode` in the
+ * language server so a later phase can swap the completion context source
+ * with minimal churn. `null` means the caret is not inside any error region
+ * and the existing (non-error) path should handle it.
+ */
+export function findErrorNodeAtOffset(
+ ast: LiquidHtmlNode,
+ offset: number,
+): { node: LiquidErrorNode; ancestors: LiquidHtmlNode[] } | null {
+ /*
+ * `walk` only hands each visited node its immediate parent, and it visits
+ * in post-order (parents after children), so the map is only complete once
+ * the traversal ends. We therefore record every parent link first, gather
+ * the error nodes that contain the offset, and resolve depth/ancestry from
+ * the finished map afterwards.
+ */
+ const parentOf = new Map{{ block.content }}
',
+].join('\n');
+
+const NO_SCHEMA_BLOCK = '{{ block.content }}
';
+
+const EMPTY_SCHEMA_BLOCK = ['{% schema %}', '{}', '{% endschema %}'].join('\n');
+
+const NO_SETTINGS_KEY_BLOCK = [
+ '{% schema %}',
+ '{"name":"Product"}',
+ '{% endschema %}',
+ '{{ block.content }}
',
+].join('\n');
+
+const HEADER_ONLY_BLOCK = [
+ '{% schema %}',
+ '{"settings":[{"type":"header","content":"X"}]}',
+ '{% endschema %}',
+ '{{ block.content }}
',
+].join('\n');
+
+async function collisionOffenses(template: string, blockSource?: string) {
+ const existingThemeFiles =
+ blockSource !== undefined ? { 'blocks/product.liquid': blockSource } : undefined;
+
+ return runLiquidCheck(
+ BlockArgumentSettingCollision,
+ template,
+ 'templates/test.liquid',
+ {},
+ existingThemeFiles,
+ );
+}
+
+describe('BlockArgumentSettingCollision', () => {
+ it('reports a plain arg that collides with a setting id', async () => {
+ const offenses = await collisionOffenses(
+ "{% block 'product', foo: 'bar' %}x{% endblock %}",
+ PRODUCT_BLOCK,
+ );
+
+ expect(offenses).toHaveLength(1);
+ expect(offenses[0].message).toContain('foo');
+ expect(offenses[0].message).toContain('block.settings.foo');
+ });
+
+ it('does not report a plain arg that is not a setting id', async () => {
+ const offenses = await collisionOffenses(
+ "{% block 'product', notasetting: 'x' %}x{% endblock %}",
+ PRODUCT_BLOCK,
+ );
+
+ expect(offenses).toHaveLength(0);
+ });
+
+ it('does not report block.settings.* system args', async () => {
+ const offenses = await collisionOffenses(
+ "{% block 'product', block.settings.foo: 'x' %}x{% endblock %}",
+ PRODUCT_BLOCK,
+ );
+
+ expect(offenses).toHaveLength(0);
+ });
+
+ it('does not report when the block file is missing', async () => {
+ const offenses = await collisionOffenses("{% block 'missing', foo: 'x' %}x{% endblock %}");
+
+ expect(offenses).toHaveLength(0);
+ });
+
+ it('does not report when the block has no schema', async () => {
+ const offenses = await collisionOffenses(
+ "{% block 'product', foo: 'x' %}x{% endblock %}",
+ NO_SCHEMA_BLOCK,
+ );
+
+ expect(offenses).toHaveLength(0);
+ });
+
+ it('does not collision-report when the schema has no settings array', async () => {
+ const offenses = await collisionOffenses(
+ "{% block 'product', foo: 'x' %}x{% endblock %}",
+ EMPTY_SCHEMA_BLOCK,
+ );
+
+ expect(offenses).toHaveLength(0);
+ });
+
+ it('does not collision-report against a schema that omits the settings key', async () => {
+ const offenses = await collisionOffenses(
+ "{% block 'product', foo: 'x' %}x{% endblock %}",
+ NO_SETTINGS_KEY_BLOCK,
+ );
+
+ expect(offenses).toHaveLength(0);
+ });
+
+ it('does not count header or paragraph entries that lack an id', async () => {
+ const offenses = await collisionOffenses(
+ "{% block 'product', header_text: 'x' %}x{% endblock %}",
+ HEADER_ONLY_BLOCK,
+ );
+
+ expect(offenses).toHaveLength(0);
+ });
+
+ it('reports each colliding arg', async () => {
+ const offenses = await collisionOffenses(
+ "{% block 'product', foo: 'a', bar: 'b' %}x{% endblock %}",
+ PRODUCT_BLOCK,
+ );
+
+ expect(offenses).toHaveLength(2);
+ });
+});
diff --git a/packages/theme-check-common/src/checks/block-argument-setting-collision/index.ts b/packages/theme-check-common/src/checks/block-argument-setting-collision/index.ts
new file mode 100644
index 000000000..47763f4b7
--- /dev/null
+++ b/packages/theme-check-common/src/checks/block-argument-setting-collision/index.ts
@@ -0,0 +1,45 @@
+import { Severity, SourceCodeType, type LiquidCheckDefinition } from '../../types';
+import type { BlockMarkup } from '@shopify/liquid-html-parser';
+import { isSystemArg } from '../common/block-doc';
+import { getBlockSchemaSettings } from '../common/block-schema';
+
+export const BlockArgumentSettingCollision: LiquidCheckDefinition = {
+ meta: {
+ code: 'BlockArgumentSettingCollision',
+ name: 'Block Argument Setting Collision',
+ docs: {
+ description:
+ "Reports a plain block tag argument whose name matches a setting id in the target block's schema. The author likely intended block.settings.section
',
+ '{% schema %}',
+ '{',
+ ' "name": "Test",',
+ ' "settings": [',
+ ...settingEntries(count),
+ ' ]',
+ '}',
+ '{% endschema %}',
+ ].join('\n');
+}
+
+describe('ExcessiveSettingsCount', () => {
+ describe('wrapper tolerated maximum', () => {
+ it('does not report at the tolerated maximum', async () => {
+ const offenses = await runLiquidCheck(
+ ExcessiveSettingsCount,
+ schemaWithSettings(TOLERATED_SETTINGS_COUNT),
+ DEFAULT_PATH,
+ );
+
+ expect(offenses).toEqual([]);
+ });
+
+ it('reports when settings exceed the tolerated maximum', async () => {
+ const offenses = await runLiquidCheck(
+ ExcessiveSettingsCount,
+ schemaWithSettings(TOLERATED_SETTINGS_COUNT + 1),
+ DEFAULT_PATH,
+ );
+
+ expect(offenses).toHaveLength(1);
+ expect(offenses[0]).toMatchObject({
+ check: 'ExcessiveSettingsCount',
+ severity: Severity.WARNING,
+ });
+ expect(offenses[0].message).toBe(
+ `This schema declares ${TOLERATED_SETTINGS_COUNT + 1} settings, which exceeds the maximum of ${TOLERATED_SETTINGS_COUNT}. Consider splitting this section or block into smaller pieces, or grouping related options with a header.`,
+ );
+ });
+ });
+
+ it('reports when count exceeds a custom maximum', async () => {
+ const offenses = await checkWithMaxSettings(schemaWithSettings(3), 2);
+
+ expect(offenses).toHaveLength(1);
+ expect(offenses[0].message).toBe(
+ `This schema declares 3 settings, which exceeds the maximum of 2. Consider splitting this section or block into smaller pieces, or grouping related options with a header.`,
+ );
+ });
+
+ it('does not report when count equals the configured maximum', async () => {
+ await expect(checkWithMaxSettings(schemaWithSettings(40), 40)).resolves.toEqual([]);
+ });
+
+ it('excludes header and paragraph entries that have no id', async () => {
+ const template = [
+ 'section
',
+ '{% schema %}',
+ '{',
+ ' "settings": [',
+ ' { "type": "header", "content": "Group" },',
+ ' { "type": "text", "id": "a", "label": "A" },',
+ ' { "type": "paragraph", "content": "Note" },',
+ ' { "type": "text", "id": "b", "label": "B" },',
+ ' { "type": "text", "id": "c", "label": "C" }',
+ ' ]',
+ '}',
+ '{% endschema %}',
+ ].join('\n');
+
+ await expect(checkWithMaxSettings(template, 3)).resolves.toEqual([]);
+ });
+
+ it('ignores settings nested in blocks', async () => {
+ const blockSettings = settingEntries(20, {
+ indent: ' ',
+ idPrefix: 'nested',
+ labelPrefix: 'N',
+ });
+ const template = [
+ 'section
',
+ '{% schema %}',
+ '{',
+ ' "settings": [',
+ ...settingEntries(5),
+ ' ],',
+ ' "blocks": [',
+ ' {',
+ ' "type": "child",',
+ ' "settings": [',
+ ...blockSettings,
+ ' ]',
+ ' }',
+ ' ]',
+ '}',
+ '{% endschema %}',
+ ].join('\n');
+
+ await expect(checkWithMaxSettings(template, 6)).resolves.toEqual([]);
+ });
+
+ it('reports above the threshold and not at the threshold', async () => {
+ const over = await checkWithMaxSettings(schemaWithSettings(6), 5);
+ expect(over).toHaveLength(1);
+
+ const atBoundary = await checkWithMaxSettings(schemaWithSettings(5), 5);
+ expect(atBoundary).toEqual([]);
+ });
+
+ it('does not report when schema is absent', async () => {
+ await expect(checkWithMaxSettings('{{ product.title }}
', 1)).resolves.toEqual([]);
+ });
+});
diff --git a/packages/theme-check-common/src/checks/excessive-settings-count/index.ts b/packages/theme-check-common/src/checks/excessive-settings-count/index.ts
new file mode 100644
index 000000000..cea47624a
--- /dev/null
+++ b/packages/theme-check-common/src/checks/excessive-settings-count/index.ts
@@ -0,0 +1,96 @@
+import {
+ isArrayNode,
+ isObjectNode,
+ SchemaProp,
+ Severity,
+ SourceCodeType,
+ type LiquidCheckDefinition,
+} from '../../types';
+import { toJSONAST } from '../../to-source-code';
+import { visit } from '../../visitor';
+import { type LiquidRawTag } from '@shopify/liquid-html-parser';
+
+/**
+ * 40 sits just above Horizon's per-file maximum of 36 top-level settings,
+ * mirroring LiquidNestingDepth: the default rests a small step above the
+ * largest healthy theme so well-formed sections and blocks never trip it.
+ *
+ * +------------+-------+
+ * | Theme | Count |
+ * +------------+-------+
+ * | base-theme | 9 |
+ * | Dawn | 23 |
+ * | Horizon | 36 |
+ * +------------+-------+
+ *
+ * Measured:
+ * - Dawn 9ccdacf81f175c7caeebc28348e50bcb02ef8fc7
+ * - Horizon 70c27a8050f66d653c4d30a3974ff07d919e4310
+ * - base-theme 31b1e1c (ose-next-theme)
+ */
+export const TOLERATED_SETTINGS_COUNT = 40;
+
+const schema = {
+ maxSettings: SchemaProp.number(TOLERATED_SETTINGS_COUNT),
+};
+
+export const ExcessiveSettingsCount: LiquidCheckDefinition{{ product.title }}
';
+
+ await expect(checkWithMaxDepth(template, 1)).resolves.toEqual([]);
+ });
+
+ it('reports the first tag that exceeds a custom threshold', async () => {
+ const threshold = 2;
+ const nestedUnless = '{% unless hidden %}';
+ const template = `
+ {% if product.available %}
+ {% for variant in product.variants %}
+ ${nestedUnless}
+ Available variant
+ {% endunless %}
+ {% endfor %}
+ {% endif %}
+ `.trim();
+ const expectedStartIndex = template.indexOf(nestedUnless);
+ const expectedEndIndex = expectedStartIndex + nestedUnless.length;
+
+ const offenses = await checkWithMaxDepth(template, threshold);
+
+ expect(offenses).toHaveLength(1);
+ expectNestingMessage(offenses[0], 3, threshold);
+ expect(offenses[0].start.index).toBe(expectedStartIndex);
+ expect(offenses[0].end.index).toBe(expectedEndIndex);
+ });
+
+ it('reports each nested control-flow tag deeper than the threshold', async () => {
+ const offenses = await checkWithMaxDepth(nestedIfs(5), 3);
+
+ expect(offenses).toHaveLength(2);
+ expectNestingMessage(offenses[0], 4, 3);
+ expectNestingMessage(offenses[1], 5, 3);
+ });
+
+ it('does not count elsif and else branches as additional nesting', async () => {
+ const template = `
+ {% if product.available %}
+ Available
+ {% elsif product.tags contains 'coming-soon' %}
+ Coming soon
+ {% else %}
+ Unavailable
+ {% endif %}
+ `.trim();
+
+ await expect(checkWithMaxDepth(template, 1)).resolves.toEqual([]);
+ });
+
+ it('counts tablerow as a nesting tag', async () => {
+ const template = `
+ {% if section.blocks.size > 0 %}
+ {% tablerow block in section.blocks %}
+ {% unless block.settings.hidden %}
+ {{ block.settings.title }}
+ {% endunless %}
+ {% endtablerow %}
+ {% endif %}
+ `.trim();
+
+ const offenses = await checkWithMaxDepth(template, 2);
+
+ expect(offenses).toHaveLength(1);
+ expectNestingMessage(offenses[0], 3, 2);
+ });
+
+ it('counts nested case blocks consistently with if, unless, and for blocks', async () => {
+ const template = `
+ {% case section.settings.layout %}
+ {% when 'grid' %}
+ {% for product in collection.products %}
+ {% if product.available %}
+ {% unless product.tags contains 'hidden' %}
+ {{ product.title }}
+ {% endunless %}
+ {% endif %}
+ {% endfor %}
+ {% endcase %}
+ `.trim();
+
+ const offenses = await checkWithMaxDepth(template, 3);
+
+ expect(offenses).toHaveLength(1);
+ expectNestingMessage(offenses[0], 4, 3);
+ });
+
+ it('does not count HTML nesting as Liquid nesting depth', async () => {
+ const template = `
+
+
+ `.trim();
+
+ await expect(checkWithMaxDepth(template, 1)).resolves.toEqual([]);
+ });
+});
diff --git a/packages/theme-check-common/src/checks/liquid-nesting-depth/index.ts b/packages/theme-check-common/src/checks/liquid-nesting-depth/index.ts
new file mode 100644
index 000000000..78571786b
--- /dev/null
+++ b/packages/theme-check-common/src/checks/liquid-nesting-depth/index.ts
@@ -0,0 +1,70 @@
+import { SchemaProp, Severity, SourceCodeType, type LiquidCheckDefinition } from '../../types';
+import { NodeTypes, type LiquidHtmlNode, type LiquidTag } from '@shopify/liquid-html-parser';
+
+/**
+ * 10 allows a small buffer above Dawn and Horizon's current maximum while
+ * still preventing deeper Liquid control-flow nesting.
+ *
+ * +------------+-------------------------------+-------+
+ * | Theme | File | Depth |
+ * +------------+-------------------------------+-------+
+ * | Dawn | sections/footer.liquid | 8 |
+ * | Horizon | snippets/header-drawer.liquid | 8 |
+ * | base-theme | blocks/_pagination.liquid | 7 |
+ * +------------+-------------------------------+-------+
+ *
+ * Measured:
+ * - Dawn 9ccdacf81f175c7caeebc28348e50bcb02ef8fc7
+ * - Horizon 70c27a8050f66d653c4d30a3974ff07d919e4310
+ * - base-theme f1bcb38b4f03ea64a12eaf5e8a79d2927602e8d7 (ose-next-theme)
+ */
+export const TOLERATED_LIQUID_NESTING_DEPTH = 10;
+
+const schema = {
+ maxDepth: SchemaProp.number(TOLERATED_LIQUID_NESTING_DEPTH),
+};
+
+const NESTING_TAGS = new Set(['if', 'unless', 'for', 'case', 'tablerow']);
+
+export const LiquidNestingDepth: LiquidCheckDefinition
+
+
+
+
+ {% if product.available %}
+ Available
+ {% endif %}
+
+ {{ title }}
',
+].join('\n');
+
+const NO_DOC_BLOCK = '';
+
+describe('MissingBlockArguments', () => {
+ it('reports when required param is missing', async () => {
+ const offenses = await runLiquidCheck(
+ MissingBlockArguments,
+ "{% block 'card', subtitle: 'sub' %}x{% endblock %}",
+ 'templates/test.liquid',
+ {},
+ { 'blocks/card.liquid': CARD_BLOCK },
+ );
+
+ expect(offenses).toHaveLength(1);
+ expect(offenses[0].message).toContain('title');
+ });
+
+ it('does not report when required param is provided', async () => {
+ const offenses = await runLiquidCheck(
+ MissingBlockArguments,
+ "{% block 'card', title: 'Hello' %}x{% endblock %}",
+ 'templates/test.liquid',
+ {},
+ { 'blocks/card.liquid': CARD_BLOCK },
+ );
+
+ expect(offenses).toHaveLength(0);
+ });
+
+ it('does not report when block file has no doc tag', async () => {
+ const offenses = await runLiquidCheck(
+ MissingBlockArguments,
+ "{% block 'card' %}x{% endblock %}",
+ 'templates/test.liquid',
+ {},
+ { 'blocks/card.liquid': NO_DOC_BLOCK },
+ );
+
+ expect(offenses).toHaveLength(0);
+ });
+
+ it('does not report when block file does not exist', async () => {
+ const offenses = await runLiquidCheck(
+ MissingBlockArguments,
+ "{% block 'missing' %}x{% endblock %}",
+ 'templates/test.liquid',
+ );
+
+ expect(offenses).toHaveLength(0);
+ });
+});
diff --git a/packages/theme-check-common/src/checks/missing-block-arguments/index.ts b/packages/theme-check-common/src/checks/missing-block-arguments/index.ts
new file mode 100644
index 000000000..86849f434
--- /dev/null
+++ b/packages/theme-check-common/src/checks/missing-block-arguments/index.ts
@@ -0,0 +1,47 @@
+import { Severity, SourceCodeType, type LiquidCheckDefinition } from '../../types';
+import type { BlockMarkup } from '@shopify/liquid-html-parser';
+import { getBlockDocParams } from '../common/block-doc';
+
+export const MissingBlockArguments: LiquidCheckDefinition = {
+ meta: {
+ code: 'MissingBlockArguments',
+ name: 'Missing Block Arguments',
+ docs: {
+ description:
+ "Reports when required arguments declared in a block's {% doc %} tag are not provided.",
+ recommended: true,
+ url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/missing-block-arguments',
+ },
+ type: SourceCodeType.LiquidHtml,
+ severity: Severity.WARNING,
+ schema: {},
+ targets: [],
+ },
+
+ create(context) {
+ return {
+ async LiquidTag(node) {
+ if (node.name !== 'block') return;
+ if (typeof node.markup === 'string') return;
+
+ const markup = node.markup as BlockMarkup;
+ const blockName = markup.name.value;
+ const docParams = await getBlockDocParams(context, blockName);
+ if (!docParams) return;
+
+ const providedParams = new Set(markup.args.map((arg) => arg.name));
+
+ for (const [paramName, param] of docParams) {
+ if (!param.required) continue;
+ if (providedParams.has(paramName)) continue;
+
+ context.report({
+ message: `Missing required argument '${paramName}' in block tag for '${blockName}'.`,
+ startIndex: node.position.start,
+ endIndex: node.position.end,
+ });
+ }
+ },
+ };
+ },
+};
diff --git a/packages/theme-check-common/src/checks/missing-template/index.ts b/packages/theme-check-common/src/checks/missing-template/index.ts
index f1cda6a07..d2b3c4b67 100644
--- a/packages/theme-check-common/src/checks/missing-template/index.ts
+++ b/packages/theme-check-common/src/checks/missing-template/index.ts
@@ -58,7 +58,12 @@ export const MissingTemplate: LiquidCheckDefinition{{ block.content }}
',
+].join('\n');
+
+const NO_SCHEMA_BLOCK = '{{ block.content }}
';
+
+const EMPTY_SETTINGS_BLOCK = [
+ '{% schema %}',
+ '{"settings":[]}',
+ '{% endschema %}',
+ '{{ block.content }}
',
+].join('\n');
+
+const NO_SETTINGS_KEY_BLOCK = [
+ '{% schema %}',
+ '{"name":"Product"}',
+ '{% endschema %}',
+ '{{ block.content }}
',
+].join('\n');
+
+async function unknownSettingOffenses(template: string, blockSource?: string) {
+ const existingThemeFiles =
+ blockSource !== undefined ? { 'blocks/product.liquid': blockSource } : undefined;
+
+ return runLiquidCheck(
+ UnknownBlockSetting,
+ template,
+ 'templates/test.liquid',
+ {},
+ existingThemeFiles,
+ );
+}
+
+describe('UnknownBlockSetting', () => {
+ it('reports a block.settings.