td-ai-tools 1.3.3 → 1.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {

package/skills/shopify-lint/SKILL.md

@@ -40,7 +40,7 @@ python3 .agents/skills/shopify-lint/scripts/shopify_lint.py --path .
 
 The script identifies files changed since the current branch's merge-base, adds staged, unstaged, and untracked files, then runs three linters over that set and merges their results into one report:
 
-- **Theme Check** — `shopify theme check --output json`. The root `.theme-check.yml` directly requires the bundled `theme-check-theory` package from this skill directory. `DisallowedScriptOrStyleTag` reports inline executable `<script>` and all `<style>` tags in modified Liquid files while allowing external-source and JSON-data scripts. `HardcodedText` reports rendered hard-coded copy, except content inside Liquid `stylesheet`, `javascript`, and `schema` tags. The generated `.theme-check.yml` also pins the upstream `StaticStylesheetAndJavascriptTags` to `error`, so Liquid written inside a `{% stylesheet %}` or `{% javascript %}` block always fails the lint.
+- **Theme Check** — `shopify theme check --output json`. The root `.theme-check.yml` directly requires the bundled `theme-check-theory` package from this skill directory. `DisallowedScriptOrStyleTag` reports inline executable `<script>` and all `<style>` tags in modified Liquid files while allowing external-source and JSON-data scripts. `HardcodedText` reports rendered hard-coded copy, except content inside Liquid `stylesheet`, `javascript`, and `schema` tags, except text beginning with `--`, which is a CSS custom property name rather than copy, and except string arguments passed to `{% render %}` and `{% include %}`, which are as often class names or size tokens as copy. The generated `.theme-check.yml` also pins the upstream `StaticStylesheetAndJavascriptTags` to `error`, so Liquid written inside a `{% stylesheet %}` or `{% javascript %}` block always fails the lint.
 - **JavaScript** — ESLint's recommended rules plus the bundled `eslint-plugin-theory`, over modified `.js` and `.mjs` files *and* the JavaScript inside `{% javascript %}` blocks of modified `.liquid` files.
 - **CSS** — `stylelint-config-standard` through the bundled `stylelint-config-theory`, over modified `.css` files *and* the CSS inside `{% stylesheet %}` blocks of modified `.liquid` files.
 
@@ -48,7 +48,7 @@ Standalone JavaScript and CSS are linted only when the **filename** contains `td
 
 The filter does **not** apply to Liquid: `{% javascript %}` and `{% stylesheet %}` blocks are linted in every modified `.liquid` file regardless of its name, because that code is Theory's either way. A `{% stylesheet 'scss' %}` block is skipped, because its body is Sass rather than CSS, as is any block commented out with `{% comment %}` or `{% raw %}`.
 
-Offenses in a Liquid block are reported at their real line and column in the `.liquid` file. Check codes say where they came from: `PascalCase` is Theme Check, `theory/…` is a Theory JavaScript rule, `eslint/…` is an upstream ESLint rule, `stylelint/…` is an upstream Stylelint rule.
+Offenses in a Liquid block are reported at their real line and column in the `.liquid` file. Positions are one-indexed in both the JSON and the text report, matching the `file:line:column` convention editors and compilers use — Theme Check's LSP-style zero-indexed rows and columns are rebased on the way in, and ESLint's and Stylelint's pass through as reported. Check codes say where they came from: `PascalCase` is Theme Check, `theory/…` is a Theory JavaScript rule, `eslint/…` is an upstream ESLint rule, `stylelint/…` is an upstream Stylelint rule.
 
 `theory/guarded-custom-element-define` and `theory/no-unapproved-imports` are errors, as are genuine ESLint correctness failures; the convention rules (`theory/disconnected-callback-cleanup`, `theory/no-class-selectors`, `theory/centralize-selectors`, `theory/require-jsdoc`) are warnings. `theory/require-jsdoc` requires named classes and functions to have JSDoc comments, including typed `@param` and `@returns` tags. The severity distinction only affects `--fail-level`: the Stop hooks run at `--fail-level warning`, so warnings block handoff too. See `eslint-plugin-theory/README.md` for every rule and its blind spots.
 

package/skills/shopify-lint/scripts/shopify_lint.py

@@ -41,9 +41,21 @@ STYLELINT_SEVERITIES = ("error", "warning")
 STYLELINT_PARSE_ERROR_RULE = "CssSyntaxError"
 
 # Theme Check reports LSP-style zero-indexed positions; ESLint and Stylelint are
-# both one-indexed.
+# both one-indexed. Positions are reported one-indexed throughout — the
+# `file:line:column` convention every editor and compiler uses — so Theme
+# Check's rows and columns are each shifted up by one and the other two runners'
+# pass through untouched.
 LINE_BASE_OFFSET = 1
 
+# Position fields carried on a Theme Check offense, rebased together so a single
+# offense never mixes indexing bases.
+THEME_CHECK_POSITION_KEYS = (
+    "start_row",
+    "start_column",
+    "end_row",
+    "end_column",
+)
+
 
 class ShopifyLintError(RuntimeError):
     """Raised when Git or Shopify CLI cannot produce filterable results."""
@@ -169,7 +181,26 @@ def run_theme_check(
 
     if not isinstance(reports, list):
         raise ShopifyLintError("Shopify Theme Check returned an unexpected JSON shape.")
-    return reports
+    return normalize_theme_check_reports(reports)
+
+
+def normalize_theme_check_reports(
+    reports: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Rebase Theme Check's zero-indexed positions onto the report's one-indexed ones."""
+    normalized = []
+    for report in reports:
+        offenses = []
+        for offense in report.get("offenses", []):
+            item = dict(offense)
+            for key in THEME_CHECK_POSITION_KEYS:
+                if key in item:
+                    item[key] = int(item[key]) + LINE_BASE_OFFSET
+            offenses.append(item)
+        entry = dict(report)
+        entry["offenses"] = offenses
+        normalized.append(entry)
+    return normalized
 
 
 def resolve_lint_target(
@@ -373,9 +404,9 @@ def normalize_stylelint_results(results: list[dict[str, Any]]) -> list[dict[str,
                     "check": stylelint_check_code(warning),
                     "severity": stylelint_severity(warning),
                     "message": str(warning.get("text", "")),
-                    "start_row": max(int(warning.get("line", 1)) - LINE_BASE_OFFSET, 0),
+                    "start_row": max(int(warning.get("line", 1)), LINE_BASE_OFFSET),
                     "start_column": max(
-                        int(warning.get("column", 1)) - LINE_BASE_OFFSET, 0
+                        int(warning.get("column", 1)), LINE_BASE_OFFSET
                     ),
                 }
             )
@@ -420,9 +451,9 @@ def normalize_eslint_results(results: list[dict[str, Any]]) -> list[dict[str, An
                     "check": eslint_check_code(message),
                     "severity": eslint_severity(message),
                     "message": str(message.get("message", "")),
-                    "start_row": max(int(message.get("line", 1)) - LINE_BASE_OFFSET, 0),
+                    "start_row": max(int(message.get("line", 1)), LINE_BASE_OFFSET),
                     "start_column": max(
-                        int(message.get("column", 1)) - LINE_BASE_OFFSET, 0
+                        int(message.get("column", 1)), LINE_BASE_OFFSET
                     ),
                 }
             )
@@ -510,8 +541,8 @@ def render_text(reports: list[dict[str, Any]], repo_root: Path) -> str:
             offense_count += 1
             severity = str(offense.get("severity", "unknown")).upper()
             check = offense.get("check", "UnknownCheck")
-            row = offense.get("start_row", 0)
-            column = offense.get("start_column", 0)
+            row = offense.get("start_row", LINE_BASE_OFFSET)
+            column = offense.get("start_column", LINE_BASE_OFFSET)
             message = offense.get("message", "")
             lines.append(f"  {severity} {check} {row}:{column} {message}".rstrip())
         lines.append("")

package/skills/shopify-lint/tests/test_shopify_lint.py

@@ -80,6 +80,35 @@ class ThemeCheckTests(unittest.TestCase):
             check=False,
         )
 
+    def test_rebases_theme_check_positions_onto_one_indexed_lines(self) -> None:
+        """Theme Check emits LSP-style zero-indexed positions; the report is one-indexed."""
+        reports = [
+            {
+                "path": "/repo/sections/td-hero.liquid",
+                "offenses": [
+                    {
+                        "check": "HardcodedText",
+                        "severity": "warning",
+                        "start_row": 0,
+                        "start_column": 4,
+                        "end_row": 2,
+                        "end_column": 9,
+                    }
+                ],
+            }
+        ]
+
+        [report] = shopify_lint.normalize_theme_check_reports(reports)
+        offense = report["offenses"][0]
+
+        self.assertEqual(offense["start_row"], 1)
+        self.assertEqual(offense["end_row"], 3)
+        self.assertEqual(offense["start_column"], 5)
+        self.assertEqual(offense["end_column"], 10)
+        # The input is not mutated in place.
+        self.assertEqual(reports[0]["offenses"][0]["start_row"], 0)
+        self.assertEqual(reports[0]["offenses"][0]["start_column"], 4)
+
     def test_filters_reports_to_changed_repo_relative_paths(self) -> None:
         root = Path("/repo")
         reports = [
@@ -360,7 +389,7 @@ class JsLintCommandTests(unittest.TestCase):
 
 
 class EslintNormalizationTests(unittest.TestCase):
-    def test_maps_severity_rule_and_zero_indexed_position(self) -> None:
+    def test_maps_severity_rule_and_position(self) -> None:
         results = [
             {
                 "filePath": "/repo/assets/td-app.js",
@@ -395,15 +424,15 @@ class EslintNormalizationTests(unittest.TestCase):
                             "check": "eslint/no-undef",
                             "severity": "error",
                             "message": "'x' is not defined.",
-                            "start_row": 3,
-                            "start_column": 2,
+                            "start_row": 4,
+                            "start_column": 3,
                         },
                         {
                             "check": "theory/no-class-selectors",
                             "severity": "warning",
                             "message": "Use a data-td-* hook.",
-                            "start_row": 8,
-                            "start_column": 0,
+                            "start_row": 9,
+                            "start_column": 1,
                         },
                     ],
                 }
@@ -684,7 +713,7 @@ class CssLintCommandTests(unittest.TestCase):
 
 
 class StylelintNormalizationTests(unittest.TestCase):
-    def test_namespaces_rules_and_zero_indexes_positions(self) -> None:
+    def test_namespaces_rules_and_maps_positions(self) -> None:
         results = [
             {
                 "path": "/theme/assets/component-td-card.css",
@@ -705,8 +734,8 @@ class StylelintNormalizationTests(unittest.TestCase):
 
         self.assertEqual(offense["check"], "stylelint/length-zero-no-unit")
         self.assertEqual(offense["severity"], "warning")
-        self.assertEqual(offense["start_row"], 3)
-        self.assertEqual(offense["start_column"], 2)
+        self.assertEqual(offense["start_row"], 4)
+        self.assertEqual(offense["start_column"], 3)
 
     def test_keeps_a_namespaced_plugin_rule_as_is(self) -> None:
         results = [
@@ -932,6 +961,32 @@ class MergeReportTests(unittest.TestCase):
     (SKILL_ROOT / "eslint-plugin-theory" / "dist").is_dir(),
     "run scripts/setup.sh to build eslint-plugin-theory",
 )
+class RenderTextTests(unittest.TestCase):
+    """The Stop hooks feed this text straight back to the agent."""
+
+    def test_prints_the_one_indexed_row_the_offense_carries(self) -> None:
+        reports = [
+            {
+                "path": "/repo/sections/td-hero.liquid",
+                "offenses": [
+                    {
+                        "check": "HardcodedText",
+                        "severity": "warning",
+                        "start_row": 12,
+                        "start_column": 4,
+                        "message": "Replace hard-coded text",
+                    }
+                ],
+            }
+        ]
+
+        rendered = shopify_lint.render_text(reports, Path("/repo"))
+
+        self.assertIn(
+            "  WARNING HardcodedText 12:4 Replace hard-coded text", rendered
+        )
+
+
 class EndToEndJsTests(unittest.TestCase):
     """Proves the Liquid line-mapping contract against the real runner."""
 
@@ -951,7 +1006,7 @@ class EndToEndJsTests(unittest.TestCase):
             "  {% endif %}",
             "{% endjavascript %}",
         ]
-        expected_row = lines.index("  const dupe = { a: 1, a: 2 };")
+        expected_row = lines.index("  const dupe = { a: 1, a: 2 };") + 1
 
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)
@@ -969,7 +1024,7 @@ class EndToEndJsTests(unittest.TestCase):
         ]
 
         self.assertEqual(len(dupe), 1)
-        # start_row is zero-indexed, matching Theme Check.
+        # start_row is one-indexed, matching the line numbers an editor shows.
         self.assertEqual(dupe[0]["start_row"], expected_row)
         self.assertEqual(dupe[0]["severity"], "error")
 
@@ -994,7 +1049,7 @@ class EndToEndCssTests(unittest.TestCase):
             "  .td-broken {}",
             "{% endstylesheet %}",
         ]
-        expected_row = lines.index("  .td-broken {}")
+        expected_row = lines.index("  .td-broken {}") + 1
 
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)
@@ -1012,13 +1067,13 @@ class EndToEndCssTests(unittest.TestCase):
         ]
 
         self.assertEqual(len(empty), 1)
-        # start_row is zero-indexed, matching Theme Check.
+        # start_row is one-indexed, matching the line numbers an editor shows.
         self.assertEqual(empty[0]["start_row"], expected_row)
         self.assertEqual(empty[0]["severity"], "error")
         # The masked interpolation is graded like any other value now: Liquid
         # does not belong in a `{% stylesheet %}` block, and Theme Check reports
         # it separately through `StaticStylesheetAndJavascriptTags`.
-        interpolated_row = lines.index("    margin: {{ section.settings.gap }}px;")
+        interpolated_row = lines.index("    margin: {{ section.settings.gap }}px;") + 1
         self.assertEqual(
             [
                 offense["check"]

package/skills/shopify-lint/theme-check-theory/.theme-check.example.yml

@@ -12,6 +12,10 @@ HardcodedText:
   enabled: true
   severity: warning
 
+RequiredLiquidDoc:
+  enabled: true
+  severity: warning
+
 # Upstream check, pinned here so the branch lint always fails on it: Shopify
 # serves `{% stylesheet %}` and `{% javascript %}` bodies verbatim, so Liquid
 # written inside one ships to the browser as literal text.

package/skills/shopify-lint/theme-check-theory/README.md

@@ -13,6 +13,7 @@ integrated into Shopify CLI. It is not compatible with the archived Ruby
 | --- | --- | --- |
 | `DisallowedScriptOrStyleTag` | warning | An inline executable `<script>` or any `<style>` tag in a Liquid file. |
 | `HardcodedText` | warning | Rendered hard-coded storefront copy that should use a dynamic content source. |
+| `RequiredLiquidDoc` | warning | A `td-` snippet or theme block without a complete Liquid doc contract. |
 | `UnusedSectionSettings` | warning | A setting declared in `{% schema %}` that is never referenced in the file. |
 | `UnguardedNullableSetting` | warning | A potentially blank setting output with `{{ }}` and no presence guard (`{% if %}`/`{% unless %}`) or `\| default`. |
 | `UnguardedMetafield` | warning | A metafield output with no presence guard or `\| default`. |
@@ -33,18 +34,61 @@ Rendered storefront copy should come from a section setting, translation key,
 metafield, or metaobject. The check reports text nodes, direct quoted output
 with `{{ }}` or `{% echo %}`, quoted `default` filter fallbacks, hard-coded
 `alt`, `title`, `placeholder`, and ARIA text attributes, and labels in the
-`value` attribute of button-like inputs. Text inside inline SVG elements and
-string literals passed as named `render` or `include` arguments are also
+`value` attribute of button-like inputs. Text inside inline SVG elements is also
 checked. It ignores technical attributes such as classes and IDs, Liquid logic
 strings, comments, punctuation-only fragments, and text made entirely of HTML
 character references.
 
+String literals passed as named `{% render %}` and `{% include %}` arguments are
+ignored. A snippet argument is as often a class name, icon key, size token, or
+heading level as it is storefront copy, and nothing at the call site separates
+the two, so checking them produced mostly false positives. Copy that a snippet
+renders is still reported inside the snippet itself, where it appears as a text
+node or a quoted output.
+
+Text beginning with `--` is ignored as a CSS custom property name: Liquid
+routinely assembles a custom property declaration before handing it to a
+`style` attribute or a `{% style %}` block, neither of which this check reads.
+Only the fragment carrying the `--` prefix is exempt, so the tail of an
+interpolated declaration — the `px;` in
+`{% capture s %}--td-gap: {{ gap }}px;{% endcapture %}` — is still reported.
+
 Content inside `{% stylesheet %}`, `{% javascript %}`, and `{% schema %}` is
 ignored. A quoted translation key passed through `t` or `translate` is also
 accepted. Short alphabetic tokens and copyright years remain reportable because
 the check cannot reliably distinguish user-facing copy from currency codes,
 units, or other intentional literals.
 
+### RequiredLiquidDoc
+
+Files whose name contains `td-` under `snippets/` or `blocks/` must contain a
+`{% doc %}` tag with a prose description and a non-empty `@example`. Every
+`@param` that is present must use LiquidDoc's `{type} name - description`
+shape; optional names such as `[heading]` are supported. LiquidDoc types are
+descriptive rather than a closed type system, so Shopify Liquid object names,
+primitive names, and project-specific type expressions are all accepted.
+
+```liquid
+{% doc %}
+  Renders a product card.
+
+  @param {product} product - The product to display.
+  @param {string} [heading] - An optional card heading.
+
+  @example
+  {% render 'td-product-card', product: product, heading: 'Featured' %}
+{% enddoc %}
+```
+
+The check does not infer missing parameters from variable lookups inside the
+file. Liquid exposes many global objects, and a snippet parameter is introduced
+at its call site, so a single-file lookup cannot reliably distinguish the two.
+To require complete parameter coverage, add a separate project-level analysis
+that indexes named arguments at static `{% render %}` call sites and compares
+their union with each target file's documented parameters. Dynamic snippet
+names and values passed with `with`/`for` require an explicit project policy or
+an allowlist.
+
 ### UnusedSectionSettings
 
 This single-file check collects every `id` under `settings` and
@@ -178,6 +222,10 @@ HardcodedText:
   enabled: true
   severity: warning
 
+RequiredLiquidDoc:
+  enabled: true
+  severity: warning
+
 # Upstream check, pinned here so the branch lint always fails on it: Shopify
 # serves `{% stylesheet %}` and `{% javascript %}` bodies verbatim, so Liquid
 # written inside one ships to the browser as literal text.

package/skills/shopify-lint/theme-check-theory/configs/recommended.yml

@@ -6,6 +6,10 @@ HardcodedText:
   enabled: true
   severity: warning
 
+RequiredLiquidDoc:
+  enabled: true
+  severity: warning
+
 UnusedSectionSettings:
   enabled: false
   severity: warning

package/skills/shopify-lint/theme-check-theory/src/checks/hardcoded-text.test.ts

@@ -98,22 +98,18 @@ describe('HardcodedText', () => {
     ]);
   });
 
-  it('reports string literals passed as render and include arguments', async () => {
+  it('ignores string literals passed as render and include arguments', async () => {
+    // A snippet argument is as often a class name, icon key, size token, or
+    // heading level as it is storefront copy, and the call site carries nothing
+    // that separates the two. The snippet body is still checked on its own.
     const source = `
       {% render 'button', label: 'Add to cart' %}
       {% include 'icon', accessible_name: "Search icon" %}
-      {% render 'button', label: section.settings.button_label %}
+      {% render 'button', variant: 'primary', size: 'large' %}
       {% render 'icon' %}
     `;
 
-    const offenses = await runLiquidCheck(HardcodedText, source);
-
-    expect(offenses).toHaveLength(2);
-    expect(
-      offenses.map(({ start, end }) =>
-        source.slice(start.index, end.index),
-      ),
-    ).toEqual(["'Add to cart'", '"Search icon"']);
+    expect(await runLiquidCheck(HardcodedText, source)).toEqual([]);
   });
 
   it('reports hard-coded default filter fallbacks', async () => {
@@ -209,6 +205,38 @@ describe('HardcodedText', () => {
     expect(await runLiquidCheck(HardcodedText, source)).toEqual([]);
   });
 
+  it('accepts CSS custom properties built in Liquid', async () => {
+    const source = `
+      {% capture card_style %}--td-card-gap: 12px;{% endcapture %}
+      {{ '--td-card-columns' }}
+      {% echo "--td-card-radius: 4px;" %}
+      {% render 'card', style_key: '--td-card-accent' %}
+      <div style="{{ card_style }}">{{ section.settings.heading }}</div>
+    `;
+
+    expect(await runLiquidCheck(HardcodedText, source)).toEqual([]);
+  });
+
+  it('still reports the tail of an interpolated custom property', async () => {
+    // The parser splits the declaration around the output tag, and only the
+    // fragment that carries the `--` prefix is exempt. The trailing unit is a
+    // text node of its own with nothing marking it as CSS.
+    const source =
+      '{% capture style %}--td-gap: {{ section.settings.gap }}px;{% endcapture %}';
+
+    const offenses = await runLiquidCheck(HardcodedText, source);
+
+    expect(
+      offenses.map(({ start, end }) => source.slice(start.index, end.index)),
+    ).toEqual(['px;']);
+  });
+
+  it('still reports copy that only mentions a custom property later', async () => {
+    const source = '{% capture note %}Set --td-gap to widen the card{% endcapture %}';
+
+    expect(await runLiquidCheck(HardcodedText, source)).toHaveLength(1);
+  });
+
   it('still reports rendered text inside other raw tags', async () => {
     const source = '{% raw %}Hard coded raw output{% endraw %}';
 

package/skills/shopify-lint/theme-check-theory/src/checks/hardcoded-text.ts

@@ -43,6 +43,12 @@ const BUTTON_INPUT_TYPES = new Set(['button', 'reset', 'submit']);
 const HTML_CHARACTER_REFERENCE =
   /&(?:#\d+|#x[\da-f]+|[a-z][\da-z]+);/giu;
 
+// A leading `--` is a CSS custom property name, never storefront copy. Liquid
+// routinely assembles custom property declarations before handing them to a
+// `style` attribute or a `{% style %}` block — places this check overlooks —
+// so the fragment that builds them is exempt too.
+const CSS_CUSTOM_PROPERTY = /^\s*--/u;
+
 type ValuedAttribute = Extract<AttributeNode, { value: unknown }>;
 
 function isValuedAttribute(node: LiquidHtmlNode): node is ValuedAttribute {
@@ -124,6 +130,8 @@ function isInlineSvgMarkup(ancestors: LiquidHtmlNode[]): boolean {
 }
 
 function hasMeaningfulText(value: string): boolean {
+  if (CSS_CUSTOM_PROPERTY.test(value)) return false;
+
   return /[\p{L}\p{N}]/u.test(
     value.replace(HTML_CHARACTER_REFERENCE, ''),
   );
@@ -300,17 +308,6 @@ export const HardcodedText: LiquidCheckDefinition = {
 
         reportInlineSvgText(node);
       },
-
-      async RenderMarkup(node) {
-        for (const argument of node.args) {
-          if (
-            argument.type === NodeTypes.NamedArgument &&
-            argument.value.type === NodeTypes.String
-          ) {
-            reportString(argument.value);
-          }
-        }
-      },
     };
   },
 };

package/skills/shopify-lint/theme-check-theory/src/checks/required-liquid-doc.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+
+import { liquidDocProblems, requiresLiquidDoc } from './required-liquid-doc';
+
+describe('RequiredLiquidDoc', () => {
+  it('targets td- Liquid snippets and blocks only', () => {
+    expect(requiresLiquidDoc('file:///theme/snippets/td-card.liquid')).toBe(true);
+    expect(requiresLiquidDoc('/theme/blocks/product-td-card.liquid')).toBe(true);
+    expect(requiresLiquidDoc('/theme/sections/td-card.liquid')).toBe(false);
+    expect(requiresLiquidDoc('/theme/snippets/card.liquid')).toBe(false);
+  });
+
+  it('accepts a description, typed parameters, and an example', () => {
+    const body = `
+      Renders a card for a product.
+      @param {product} product - The product displayed by the card.
+      @param {string} [heading] - An optional heading.
+      @example
+      {% render 'td-card', product: product, heading: 'Featured' %}
+    `;
+    expect(liquidDocProblems(body)).toEqual([]);
+  });
+
+  it('requires both a description and non-empty example', () => {
+    expect(liquidDocProblems('@example\n').map(({ message }) => message)).toEqual([
+      'Liquid doc must include a description before its annotations',
+      'Liquid doc must include an @example with example markup',
+    ]);
+  });
+
+  it('requires types and descriptions on documented parameters', () => {
+    const body = `
+      Renders a card.
+      @param product - The product.
+      @param {string} heading
+      @example
+      {% render 'td-card', product: product %}
+    `;
+    expect(liquidDocProblems(body).map(({ message }) => message)).toEqual([
+      'Liquid doc @param must include a type in braces',
+      'Liquid doc @param must include a description after " - "',
+      'Liquid doc @param must include a type in braces',
+      'Liquid doc @param must include a description after " - "',
+    ]);
+  });
+});

package/skills/shopify-lint/theme-check-theory/src/checks/required-liquid-doc.ts

@@ -0,0 +1,111 @@
+import type { LiquidRawTag } from '@shopify/liquid-html-parser';
+import {
+  LiquidCheckDefinition,
+  Severity,
+  SourceCodeType,
+} from '@shopify/theme-check-common';
+
+type DocumentationProblem = { message: string; offset: number; length: number };
+
+const PARAM_LINE = /^[ \t]*@param[ \t]+(.*)$/gm;
+const COMPLETE_PARAM = /^\{([^}\n]+)\}\s+(\[[^\]\n]+\]|[^\s-]+)\s+-\s+(.+)$/;
+
+/** Returns true for td-named snippets and theme blocks. */
+export function requiresLiquidDoc(uri: string): boolean {
+  const path = decodeURIComponent(uri).replace(/\\/g, '/').split(/[?#]/, 1)[0];
+  const match = path.match(/(?:^|\/)(snippets|blocks)\/([^/]+)\.liquid$/i);
+  return Boolean(match?.[2].toLowerCase().includes('td-'));
+}
+
+/** Validates the documented contract without mistaking Shopify globals for parameters. */
+export function liquidDocProblems(body: string): DocumentationProblem[] {
+  const problems: DocumentationProblem[] = [];
+  const firstAnnotation = body.search(/^[ \t]*@\w+/m);
+  const description = body.slice(0, firstAnnotation < 0 ? body.length : firstAnnotation).trim();
+
+  if (!description) {
+    problems.push({
+      message: 'Liquid doc must include a description before its annotations',
+      offset: 0,
+      length: Math.max(body.length, 1),
+    });
+  }
+
+  const example = body.match(
+    /^[ \t]*@example[^\n]*\n([\s\S]*?)(?=^[ \t]*@\w+|(?![\s\S]))/m,
+  );
+  if (!example || !example[1].trim()) {
+    problems.push({
+      message: 'Liquid doc must include an @example with example markup',
+      offset: 0,
+      length: Math.max(body.length, 1),
+    });
+  }
+
+  for (const match of body.matchAll(PARAM_LINE)) {
+    const complete = match[1].trim().match(COMPLETE_PARAM);
+    const offset = match.index ?? 0;
+    if (!complete?.[1].trim()) {
+      problems.push({
+        message: 'Liquid doc @param must include a type in braces',
+        offset,
+        length: match[0].length,
+      });
+    }
+    if (!complete?.[3].trim()) {
+      problems.push({
+        message: 'Liquid doc @param must include a description after " - "',
+        offset,
+        length: match[0].length,
+      });
+    }
+  }
+
+  return problems;
+}
+
+export const RequiredLiquidDoc: LiquidCheckDefinition = {
+  meta: {
+    code: 'RequiredLiquidDoc',
+    name: 'Require documentation for td- snippets and theme blocks',
+    docs: {
+      description:
+        'Requires td- snippets and blocks to have a Liquid doc description and example, and validates documented parameters.',
+      recommended: true,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+  },
+  create(context) {
+    const uri = (context as unknown as { file?: { uri?: string } }).file?.uri ?? '';
+    if (!requiresLiquidDoc(uri)) return {};
+
+    const docs: LiquidRawTag[] = [];
+    return {
+      async LiquidRawTag(node) {
+        if (node.name === 'doc') docs.push(node);
+      },
+      async onCodePathEnd() {
+        if (docs.length === 0) {
+          context.report({
+            message: 'td- snippets and blocks must include a {% doc %} tag',
+            startIndex: 0,
+            endIndex: 1,
+          });
+          return;
+        }
+
+        const doc = docs[0];
+        for (const problem of liquidDocProblems(doc.body.value)) {
+          const startIndex = doc.body.position.start + problem.offset;
+          context.report({
+            message: problem.message,
+            startIndex,
+            endIndex: startIndex + problem.length,
+          });
+        }
+      },
+    };
+  },
+};

package/skills/shopify-lint/theme-check-theory/src/index.test.ts

@@ -8,6 +8,7 @@ describe('theme-check-theory module', () => {
     expect(checks.map(({ meta }) => meta.code)).toEqual([
       'DisallowedScriptOrStyleTag',
       'HardcodedText',
+      'RequiredLiquidDoc',
       'UnusedSectionSettings',
       'UnguardedNullableSetting',
       'UnguardedMetafield',
@@ -24,6 +25,7 @@ describe('theme-check-theory module', () => {
     ).toEqual({
       DisallowedScriptOrStyleTag: true,
       HardcodedText: true,
+      RequiredLiquidDoc: true,
       UnusedSectionSettings: false,
       UnguardedNullableSetting: true,
       UnguardedMetafield: true,

package/skills/shopify-lint/theme-check-theory/src/index.ts

@@ -1,5 +1,6 @@
 import { DisallowedScriptOrStyleTag } from './checks/disallowed-script-or-style-tag';
 import { HardcodedText } from './checks/hardcoded-text';
+import { RequiredLiquidDoc } from './checks/required-liquid-doc';
 import { UnusedSectionSettings } from './checks/unused-section-settings';
 import { UnguardedMetafield } from './checks/unguarded-metafield';
 import { UnguardedMetaobject } from './checks/unguarded-metaobject';
@@ -7,6 +8,7 @@ import { UnguardedNullableSetting } from './checks/unguarded-nullable-setting';
 
 export { DisallowedScriptOrStyleTag } from './checks/disallowed-script-or-style-tag';
 export { HardcodedText } from './checks/hardcoded-text';
+export { RequiredLiquidDoc } from './checks/required-liquid-doc';
 export { UnusedSectionSettings } from './checks/unused-section-settings';
 export { UnguardedMetafield } from './checks/unguarded-metafield';
 export { UnguardedMetaobject } from './checks/unguarded-metaobject';
@@ -18,6 +20,7 @@ export {
 export const checks = [
   DisallowedScriptOrStyleTag,
   HardcodedText,
+  RequiredLiquidDoc,
   UnusedSectionSettings,
   UnguardedNullableSetting,
   UnguardedMetafield,

package/skills/shopify-lint/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +0,0 @@
-{"version":"4.1.10","results":[[":eslint-plugin-theory/src/rules/guarded-custom-element-define.test.ts",{"duration":0,"failed":true}]]}