td-ai-tools 1.2.5 → 1.2.6

package/package.json

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

package/skills/README.md

@@ -16,7 +16,7 @@
 - `pull-request-statamic`: Generates GitHub pull request descriptions for Statamic and Laravel development by analyzing git diffs and…
 - `record-changes`: Update `docs/changes.md` by summarizing the current branch against the primary development branch.
 - `shopify-cli`: Shopify CLI workflows for theme development.
-- `shopify-lint`: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks while reporting and failing only on…
+- `shopify-lint`: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks, including warnings for hard-coded…
 - `stylesheet-migration`: Migrate Shopify Liquid `{% stylesheet %}` blocks into theme CSS assets using bundled Python scripts.
 - `td-js-vanilla-rules`: Theory Digital vanilla JavaScript standards for Shopify theme work.
 - `td-review`: Run parallel code review agents on a PR (including TD theme compliance) and produce a synthesized findings…

package/skills/shopify-lint/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: shopify-lint
-version: 1.1.0
-description: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks while reporting and failing only on offenses in files modified on the current Git branch. Use when Codex needs to lint a Shopify theme, validate branch-scoped Liquid or theme changes, enforce Theory theme rules, or avoid surfacing pre-existing Theme Check offenses from untouched files.
+version: 1.3.0
+description: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks, including warnings for hard-coded storefront text and script or style tags in Liquid, while reporting and failing only on offenses in files modified on the current Git branch. Use when Codex needs to lint a Shopify theme, validate branch-scoped Liquid or theme changes, enforce Theory theme rules, or avoid surfacing pre-existing Theme Check offenses from untouched files.
 ---
 
 # Shopify Lint
@@ -17,7 +17,7 @@ bash .agents/skills/shopify-lint/scripts/setup.sh
 Installing with `td-ai-tools install --setup shopify-lint` runs this automatically. The script:
 
 1. Runs `npm install && npm run build` inside `theme-check-theory/`, producing `dist/index.js` — the CommonJS entry point the root `.theme-check.yml` requires.
-2. Writes a `.theme-check.yml` at the project root wiring in the bundled checks. If one already exists it is left untouched; ensure its `require:` list includes `./.agents/skills/shopify-lint/theme-check-theory`.
+2. Writes a `.theme-check.yml` at the project root wiring in the bundled checks. If one already exists it is left untouched; ensure its `require:` list includes `./.agents/skills/shopify-lint/theme-check-theory` and both `DisallowedScriptOrStyleTag` and `HardcodedText` are enabled.
 3. Through the installer's shared project-hook setup, installs matching Claude and Codex Stop hooks and merges their registrations into `.claude/settings.json` and `.codex/hooks.json` without replacing unrelated settings or hooks. Re-running setup updates the Shopify Lint hook in place instead of duplicating it.
 
 The Stop hooks run this skill's branch-scoped lint before handoff, return modified-file offenses to the agent, and allow handoff after three unsuccessful fix rounds. They require `jq`, `python3`, and Shopify CLI to be available when the hook runs. Directly running `scripts/setup.sh` performs the package build and Theme Check configuration; use `td-ai-tools install --setup` or `td-ai-tools update --setup` to apply the shared hook manifest as well.
@@ -32,7 +32,7 @@ Run the bundled Python script from the Shopify theme root:
 python3 .agents/skills/shopify-lint/scripts/shopify_lint.py --path .
 ```
 
-The script runs `shopify theme check --output json`, identifies files changed since the current branch's merge-base, adds staged, unstaged, and untracked files, and emits only reports whose paths are in that set. The root `.theme-check.yml` directly requires the bundled `theme-check-theory` package from this skill directory.
+The script runs `shopify theme check --output json`, identifies files changed since the current branch's merge-base, adds staged, unstaged, and untracked files, and emits only reports whose paths are in that set. The root `.theme-check.yml` directly requires the bundled `theme-check-theory` package from this skill directory. `DisallowedScriptOrStyleTag` reports HTML `<script>` and `<style>` tags in modified Liquid files. `HardcodedText` reports rendered hard-coded copy, except content inside Liquid `stylesheet`, `javascript`, and `schema` tags.
 
 ## Workflow
 

package/skills/shopify-lint/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Shopify Lint"
-  short_description: "Lint modified theme files with Theory checks"
+  short_description: "Lint modified Shopify theme files"
   default_prompt: "Use $shopify-lint to run Theme Check for files modified on my current branch."

package/skills/shopify-lint/scripts/setup.sh

@@ -50,11 +50,27 @@ extends:
 require:
   - ./.agents/skills/shopify-lint/theme-check-theory
 
+DisallowedScriptOrStyleTag:
+  enabled: true
+  severity: warning
+
+HardcodedText:
+  enabled: true
+  severity: warning
+
 UnusedSectionSettings:
+  enabled: false
+  severity: warning
+
+UnguardedNullableSetting:
+  enabled: true
+  severity: warning
+
+UnguardedMetafield:
   enabled: true
   severity: warning
 
-UnguardedTextSetting:
+UnguardedMetaobject:
   enabled: true
   severity: warning
 YAML

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

@@ -4,11 +4,26 @@ extends:
 require:
   - ./node_modules/theme-check-theory
 
+DisallowedScriptOrStyleTag:
+  enabled: true
+  severity: warning
+
+HardcodedText:
+  enabled: true
+  severity: warning
+
 UnusedSectionSettings:
+  enabled: false
+  severity: warning
+
+UnguardedNullableSetting:
   enabled: true
   severity: warning
 
-UnguardedTextSetting:
+UnguardedMetafield:
   enabled: true
   severity: warning
 
+UnguardedMetaobject:
+  enabled: true
+  severity: warning

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

@@ -11,8 +11,31 @@ integrated into Shopify CLI. It is not compatible with the archived Ruby
 
 | Code | Severity | What it catches |
 | --- | --- | --- |
+| `DisallowedScriptOrStyleTag` | warning | An HTML `<script>` or `<style>` tag in a Liquid file. |
+| `HardcodedText` | warning | Rendered hard-coded storefront copy that should use a dynamic content source. |
 | `UnusedSectionSettings` | warning | A setting declared in `{% schema %}` that is never referenced in the file. |
-| `UnguardedTextSetting` | warning | A text-like setting output with `{{ }}` and no presence guard (`{% if %}`/`{% unless %}`) or `\| default`. |
+| `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`. |
+| `UnguardedMetaobject` | warning | A metaobject entry output with no presence guard or `\| default`. |
+
+### DisallowedScriptOrStyleTag
+
+HTML `<script>` and `<style>` tags keep JavaScript and CSS embedded in Liquid
+files. Move their contents to theme assets or the appropriate Shopify Liquid
+tags instead. HTML comments and similarly named elements such as
+`<script-template>` are ignored.
+
+### HardcodedText
+
+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 %}`, and hard-coded `alt`, `title`, `placeholder`, and
+ARIA text attributes. It ignores technical attributes such as classes and IDs,
+Liquid logic strings, comments, and punctuation-only fragments.
+
+Content inside `{% stylesheet %}`, `{% javascript %}`, and `{% schema %}` is
+ignored. A quoted translation key passed through `t` or `translate` is also
+accepted.
 
 ### UnusedSectionSettings
 
@@ -25,31 +48,62 @@ If a file uses dynamic access such as `section.settings[key]`, or passes an
 entire settings object elsewhere, the check cannot prove which setting is
 unused. It therefore stays silent for the whole file to avoid false positives.
 
-### UnguardedTextSetting
+This check is disabled by default. Enable it explicitly when a theme's section
+settings are expected to be fully traceable within each file:
+
+```yaml
+UnusedSectionSettings:
+  enabled: true
+  severity: warning
+```
 
-Text-like settings render as an empty string when a merchant leaves them blank,
-so outputting them unguarded is a recurring bug source. A setting is considered
-handled if, anywhere in the file, it is either tested in an `if`, `unless`,
-`elsif`, or `case` conditional, or output with a `default` filter.
+### UnguardedNullableSetting
 
-Version 1 is deliberately coarse and per-file. It favors near-zero false
-positives over catching a setting guarded in one branch and output raw in
-another.
+Many settings can return an empty, `blank`, or `nil` value when a merchant
+leaves them unset or their selected resource is no longer available. Outputting
+them unguarded is a recurring bug source. Each output is evaluated independently.
+It is considered guarded when its active `if`, `unless`, `elsif`, or `case`
+branch tests that setting, or when that output uses a `default` filter. A guard
+or default on one invocation does not suppress offenses for unguarded
+invocations elsewhere in the file.
 
-The setting types considered text-like are configurable with
-`textualSettingTypes`. The defaults are `text`, `textarea`, `richtext`,
-`inline_richtext`, `html`, `liquid`, and `url`.
+The setting types checked are configurable with the `nullableSettingTypes`
+option. The defaults are `number`, `text`, `textarea`, `article`,
+`article_list`, `blog`, `collection`, `collection_list`, `image_picker`,
+`link_list`, `metaobject`, `metaobject_list`, `page`, `product`,
+`product_list`, `richtext`, `inline_richtext`, `html`, `liquid`, `url`,
+`video`, and `video_url`. Color-related settings are excluded because an unset
+color can resolve to a non-null fallback such as `transparent`.
 
 ```yaml
-UnguardedTextSetting:
+UnguardedNullableSetting:
   enabled: true
   severity: warning
-  textualSettingTypes:
+  nullableSettingTypes:
     - text
     - textarea
     - image_picker
 ```
 
+### UnguardedMetafield and UnguardedMetaobject
+
+[Metafields](https://shopify.dev/docs/api/liquid/objects/metafield) are
+identified from the static `resource.metafields.namespace.key` access path,
+and [metaobjects](https://shopify.dev/docs/api/liquid/objects/metaobject) from
+`metaobjects.type.handle`. Outputting the object itself or any descendant, such
+as a metafield's `value` or a metaobject's field, requires a guard on the same
+object or a `default` filter on that output.
+
+Both dot and static square-bracket notation are supported. Dynamic namespace,
+key, type, and handle lookups are ignored because the selected object cannot be
+identified statically. The singular `metaobject` drop available inside a
+metaobject template is also ignored because the template is already rendering
+that entry.
+
+All three nullability checks share the same branch and `default`-filter
+analysis. A guard applies only inside its active `if`, `unless`, `elsif`, or
+`case` branch and only to the matching setting, metafield, or metaobject.
+
 ## Usage in a project
 
 Install the module as a development dependency:
@@ -67,11 +121,27 @@ extends:
 require:
   - ./node_modules/theme-check-theory
 
+DisallowedScriptOrStyleTag:
+  enabled: true
+  severity: warning
+
+HardcodedText:
+  enabled: true
+  severity: warning
+
 UnusedSectionSettings:
+  enabled: false
+  severity: warning
+
+UnguardedNullableSetting:
+  enabled: true
+  severity: warning
+
+UnguardedMetafield:
   enabled: true
   severity: warning
 
-UnguardedTextSetting:
+UnguardedMetaobject:
   enabled: true
   severity: warning
 ```
@@ -118,6 +188,7 @@ real Theme Check parser and traversal rather than a mocked AST.
 4. Add it to `configs/recommended.yml`.
 
 Shared schema parsing and setting-reference helpers live in `src/utils/ast.ts`.
-Their node shapes are verified against `@shopify/liquid-html-parser` 2.9.x;
-run the tests when upgrading that dependency.
-
+Null-guard analysis and nullable-object check construction live in
+`src/utils/null-guard.ts` and `src/utils/nullable-output-check.ts`. Their node
+shapes are verified against `@shopify/liquid-html-parser` 2.9.x; run the tests
+when upgrading that dependency.

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

@@ -1,8 +1,23 @@
+DisallowedScriptOrStyleTag:
+  enabled: true
+  severity: warning
+
+HardcodedText:
+  enabled: true
+  severity: warning
+
 UnusedSectionSettings:
+  enabled: false
+  severity: warning
+
+UnguardedNullableSetting:
   enabled: true
   severity: warning
 
-UnguardedTextSetting:
+UnguardedMetafield:
   enabled: true
   severity: warning
 
+UnguardedMetaobject:
+  enabled: true
+  severity: warning

package/skills/shopify-lint/theme-check-theory/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "theme-check-theory",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "theme-check-theory",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "license": "UNLICENSED",
       "dependencies": {
         "@shopify/liquid-html-parser": "2.9.2",

package/skills/shopify-lint/theme-check-theory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theme-check-theory",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Theory Digital's custom Shopify Theme Check rules",
   "type": "commonjs",
   "main": "dist/index.js",

package/skills/shopify-lint/theme-check-theory/src/checks/disallowed-script-or-style-tag.test.ts

@@ -0,0 +1,54 @@
+import {
+  runLiquidCheck,
+} from '@shopify/theme-check-common/dist/test/test-helper';
+import { describe, expect, it } from 'vitest';
+
+import { DisallowedScriptOrStyleTag } from './disallowed-script-or-style-tag';
+
+describe('DisallowedScriptOrStyleTag', () => {
+  it('reports script and style tags', async () => {
+    const source = `
+      <script src="{{ 'theme.js' | asset_url }}" defer></script>
+      <style>.example { color: red; }</style>
+    `;
+
+    const offenses = await runLiquidCheck(DisallowedScriptOrStyleTag, source);
+
+    expect(offenses).toHaveLength(2);
+    expect(offenses.map(({ message }) => message)).toEqual([
+      'Do not include <script> tags in Liquid files',
+      'Do not include <style> tags in Liquid files',
+    ]);
+    expect(
+      offenses.every(({ check }) => check === 'DisallowedScriptOrStyleTag'),
+    ).toBe(true);
+  });
+
+  it('reports case variants and self-closing tags', async () => {
+    const source = `
+      <SCRIPT type="application/json">{}</SCRIPT>
+      <STYLE />
+    `;
+
+    const offenses = await runLiquidCheck(DisallowedScriptOrStyleTag, source);
+
+    expect(offenses).toHaveLength(2);
+    expect(offenses.map(({ message }) => message)).toEqual([
+      'Do not include <script> tags in Liquid files',
+      'Do not include <style> tags in Liquid files',
+    ]);
+  });
+
+  it('ignores tags in comments and similarly named elements', async () => {
+    const source = `
+      <!-- <script></script> -->
+      {% comment %}<style></style>{% endcomment %}
+      <script-template></script-template>
+      <div style="color: red"></div>
+    `;
+
+    expect(
+      await runLiquidCheck(DisallowedScriptOrStyleTag, source),
+    ).toEqual([]);
+  });
+});

package/skills/shopify-lint/theme-check-theory/src/checks/disallowed-script-or-style-tag.ts

@@ -0,0 +1,77 @@
+import {
+  HtmlElement,
+  HtmlSelfClosingElement,
+  NodeTypes,
+} from '@shopify/liquid-html-parser';
+import {
+  LiquidCheckDefinition,
+  Severity,
+  SourceCodeType,
+} from '@shopify/theme-check-common';
+
+const DISALLOWED_TAGS = new Set(['script', 'style']);
+
+type NamedHtmlNode = HtmlElement | HtmlSelfClosingElement;
+
+function staticTagName(node: NamedHtmlNode): string | null {
+  if (
+    node.name.length !== 1 ||
+    node.name[0].type !== NodeTypes.TextNode
+  ) {
+    return null;
+  }
+
+  return node.name[0].value.toLowerCase();
+}
+
+export const DisallowedScriptOrStyleTag: LiquidCheckDefinition = {
+  meta: {
+    code: 'DisallowedScriptOrStyleTag',
+    name: 'Prevent script and style tags in Liquid',
+    docs: {
+      description: 'Reports HTML script and style tags in Liquid files.',
+      recommended: true,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+  },
+  create(context) {
+    function report(tagName: string, startIndex: number, endIndex: number) {
+      if (!DISALLOWED_TAGS.has(tagName)) return;
+
+      context.report({
+        message: `Do not include <${tagName}> tags in Liquid files`,
+        startIndex,
+        endIndex,
+      });
+    }
+
+    function checkNamedNode(node: NamedHtmlNode) {
+      const tagName = staticTagName(node);
+      if (!tagName) return;
+
+      report(
+        tagName,
+        node.blockStartPosition.start,
+        node.blockStartPosition.end,
+      );
+    }
+
+    return {
+      async HtmlRawNode(node) {
+        report(
+          node.name.toLowerCase(),
+          node.blockStartPosition.start,
+          node.blockStartPosition.end,
+        );
+      },
+      async HtmlElement(node) {
+        checkNamedNode(node);
+      },
+      async HtmlSelfClosingElement(node) {
+        checkNamedNode(node);
+      },
+    };
+  },
+};

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

@@ -0,0 +1,102 @@
+import {
+  runLiquidCheck,
+} from '@shopify/theme-check-common/dist/test/test-helper';
+import { describe, expect, it } from 'vitest';
+
+import { HardcodedText } from './hardcoded-text';
+
+describe('HardcodedText', () => {
+  it('reports rendered text and direct string output', async () => {
+    const source = `
+      Welcome to our store
+      <h2>Featured products</h2>
+      {{ 'Limited edition' }}
+      {% echo "Shop now" %}
+    `;
+
+    const offenses = await runLiquidCheck(HardcodedText, source);
+
+    expect(offenses).toHaveLength(4);
+    expect(
+      offenses.every(({ check }) => check === 'HardcodedText'),
+    ).toBe(true);
+    expect(
+      offenses.every(
+        ({ message }) =>
+          message ===
+          'Replace hard-coded text with a section setting, translation key, metafield, or metaobject',
+      ),
+    ).toBe(true);
+  });
+
+  it('reports hard-coded text in common user-facing attributes', async () => {
+    const source = `
+      <img src="{{ image | image_url }}" alt="Product photo">
+      <button title='Close dialog' aria-label="Close">×</button>
+      <input placeholder="Email address">
+    `;
+
+    const offenses = await runLiquidCheck(HardcodedText, source);
+
+    expect(offenses).toHaveLength(4);
+  });
+
+  it('reports static fragments in otherwise dynamic rendered text', async () => {
+    const source = `
+      <p>Welcome, {{ customer.name }}!</p>
+      <img alt="Photo of {{ product.title }}" src="{{ product.featured_image | image_url }}">
+    `;
+
+    const offenses = await runLiquidCheck(HardcodedText, source);
+
+    expect(offenses).toHaveLength(2);
+  });
+
+  it('accepts settings, translation keys, metafields, and metaobjects', async () => {
+    const source = `
+      <h2>{{ section.settings.heading }}</h2>
+      <p>{{ 'general.welcome' | t }}</p>
+      <p>{{ "general.subtitle" | translate }}</p>
+      <p>{{ product.metafields.content.description }}</p>
+      <p>{{ metaobjects.testimonials.homepage.quote }}</p>
+      <img alt="{{ section.settings.image_alt }}" src="{{ section.settings.image | image_url }}">
+    `;
+
+    expect(await runLiquidCheck(HardcodedText, source)).toEqual([]);
+  });
+
+  it.each([
+    [
+      'stylesheet',
+      '{% stylesheet %}.card::after { content: "Hard coded"; }{% endstylesheet %}',
+    ],
+    [
+      'javascript',
+      '{% javascript %}console.log("Hard coded");{% endjavascript %}',
+    ],
+    [
+      'schema',
+      '{% schema %}{"name":"Hard coded","settings":[]}{% endschema %}',
+    ],
+  ])('ignores text inside the %s raw tag', async (_, source) => {
+    expect(await runLiquidCheck(HardcodedText, source)).toEqual([]);
+  });
+
+  it('ignores comments, technical attributes, punctuation, and Liquid logic strings', async () => {
+    const source = `
+      <!-- Hard coded HTML comment -->
+      {% comment %}Hard coded Liquid comment{% endcomment %}
+      <div class="hard-coded" id="hard-coded" data-label="Hard coded">—</div>
+      {% assign state = 'active' %}
+      {% if request.page_type == 'product' %}{{ product.title }}{% endif %}
+    `;
+
+    expect(await runLiquidCheck(HardcodedText, source)).toEqual([]);
+  });
+
+  it('still reports rendered text inside other raw tags', async () => {
+    const source = '{% raw %}Hard coded raw output{% endraw %}';
+
+    expect(await runLiquidCheck(HardcodedText, source)).toHaveLength(1);
+  });
+});