Added more tests and added changeset

Author: shoplando

.changeset/hungry-ravens-sneeze.md

@@ -0,0 +1,5 @@
+---
+'@shopify/theme-check-common': minor
+---
+
+Introducing `doc` tags inside the new `snippet` tag, as well as making the theme check more rigorous with where the `doc` tag is placed

packages/theme-check-common/src/checks/unsupported-doc-tag/index.spec.ts

@@ -14,7 +14,7 @@ describe('Module: UnsupportedDocTag', () => {
 
     expect(offenses).to.have.length(1);
     expect(offenses[0].message).to.equal(
-      'The `doc` tag can only be used within a snippet or block.',
+      'The `doc` must be placed directly within an inline snippet tag, not nested inside other tags',
     );
   });
 
@@ -42,4 +42,39 @@ describe('Module: UnsupportedDocTag', () => {
 
     expect(offenses).to.be.empty;
   });
+
+  it('should not report an error when `doc` tag is used inside inline snippet', async () => {
+    const layoutSourceCode = `
+      {% snippet %}
+        ${sourceCode}
+      {% endsnippet %}
+    `;
+
+    const offenses = await runLiquidCheck(
+      UnsupportedDocTag,
+      layoutSourceCode,
+      'file://layout/theme.liquid',
+    );
+
+    expect(offenses).to.be.empty;
+  });
+
+  it('should report an error when `doc` tag is nested inside a block within a snippet file', async () => {
+    const nestedSourceCode = `
+      {% if true %}
+        ${sourceCode}
+      {% endif %}
+    `;
+
+    const offenses = await runLiquidCheck(
+      UnsupportedDocTag,
+      nestedSourceCode,
+      'file://snippets/file.liquid',
+    );
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal(
+      'The `doc` tag must be a top-level tag within a snippet/block file',
+    );
+  });
 });