td-ai-tools 1.2.1 → 1.2.2

package/package.json

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

package/skills/README.md

@@ -18,6 +18,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 offenses in files modified on the current Git branch.
 - `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

@@ -0,0 +1,50 @@
+---
+name: shopify-lint
+version: 1.0.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.
+---
+
+# Shopify Lint
+
+## Setup
+
+The bundled `theme-check-theory` custom-check package ships as TypeScript source only; its `node_modules` and compiled `dist/` are not committed. Run setup once before the first run (and after upgrading the skill):
+
+```bash
+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`.
+
+Keep these dependencies inside `theme-check-theory/node_modules`; do not install Node dependencies at the theme root.
+
+## Usage
+
+Run the bundled Python script from the Shopify theme root:
+
+```bash
+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.
+
+## Workflow
+
+1. Confirm `shopify` and `python3` are available.
+2. Run the bundled script instead of calling `shopify theme check` directly.
+3. Treat exit code `0` as no failing offenses in modified files, `1` as filtered offenses at or above the fail level, and `2` as a Git, CLI, or JSON-processing error.
+4. Fix reported issues and rerun until the command passes. Do not fix offenses in untouched files unless the user expands the scope.
+5. Keep custom-check dependencies inside `theme-check-theory/node_modules`. Do not install Node dependencies at the theme root.
+
+The default base is `origin/HEAD`, then `origin/main`, `main`, `origin/master`, or `master`. Override it when needed:
+
+```bash
+python3 .agents/skills/shopify-lint/scripts/shopify_lint.py --path . --base-ref origin/develop
+```
+
+Set `SHOPIFY_LINT_BASE_REF` for the same override in automation. Use `--format json` for machine-readable filtered output and `--fail-level warning` or `--fail-level info` for stricter runs. When passing `--config <path>`, preserve the bundled package's `require` entry or the Theory checks will not load.
+
+Do not use Theme Check auto-correction through this workflow because it can modify untouched files before filtering.

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

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

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

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shopify-lint setup
+#
+# Run automatically by the installer (`--setup`) from the installed skill
+# directory, or manually with `bash scripts/setup.sh`. It:
+#   1. Builds the bundled `theme-check-theory` custom-check package
+#      (its node_modules and dist/ are intentionally not committed).
+#   2. Writes a `.theme-check.yml` at the project root that wires the bundled
+#      checks into Shopify CLI Theme Check.
+
+SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+PKG_DIR="$SKILL_DIR/theme-check-theory"
+
+# 1. Build the bundled custom-check package.
+echo "shopify-lint setup: building theme-check-theory in $PKG_DIR"
+cd "$PKG_DIR"
+npm install
+npm run build
+
+# 2. Generate the project-root .theme-check.yml.
+#
+# The installed layout is <project>/<.agents|.claude>/skills/shopify-lint, so
+# the project root is three levels above the skill directory. Guard against
+# running outside that layout (e.g. from the catalog repo) to avoid writing the
+# config into an unexpected directory.
+TARGET_DIR="$(cd "$SKILL_DIR/../.." && pwd)"
+TARGET_BASE="$(basename "$TARGET_DIR")"
+if [[ "$TARGET_BASE" != ".agents" && "$TARGET_BASE" != ".claude" ]]; then
+  echo "shopify-lint setup: unrecognized install layout ($TARGET_DIR); skipping .theme-check.yml generation." >&2
+  exit 0
+fi
+
+PROJECT_ROOT="$(dirname "$TARGET_DIR")"
+THEME_CHECK_FILE="$PROJECT_ROOT/.theme-check.yml"
+
+if [[ -f "$THEME_CHECK_FILE" ]]; then
+  echo "shopify-lint setup: $THEME_CHECK_FILE already exists; leaving it unchanged."
+  echo "  Ensure its 'require:' list includes ./.agents/skills/shopify-lint/theme-check-theory"
+  exit 0
+fi
+
+cat > "$THEME_CHECK_FILE" <<'YAML'
+extends:
+  - theme-check:recommended
+
+require:
+  - ./.agents/skills/shopify-lint/theme-check-theory
+
+UnusedSectionSettings:
+  enabled: true
+  severity: warning
+
+UnguardedTextSetting:
+  enabled: true
+  severity: warning
+YAML
+
+echo "shopify-lint setup: wrote $THEME_CHECK_FILE"

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

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""Run Shopify Theme Check and report offenses only for branch-modified files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+SEVERITY_RANK = {"error": 0, "warning": 1, "info": 2}
+
+
+class ShopifyLintError(RuntimeError):
+    """Raised when Git or Shopify CLI cannot produce filterable results."""
+
+
+def run_command(command: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def git_output(repo_root: Path, *arguments: str) -> str:
+    result = run_command(["git", *arguments], repo_root)
+    if result.returncode != 0:
+        detail = result.stderr.strip() or result.stdout.strip()
+        raise ShopifyLintError(f"Git command failed: {detail}")
+    return result.stdout
+
+
+def find_repo_root(theme_path: Path) -> Path:
+    result = run_command(["git", "rev-parse", "--show-toplevel"], theme_path)
+    if result.returncode != 0:
+        raise ShopifyLintError("Theme path must be inside a Git repository.")
+    return Path(result.stdout.strip()).resolve()
+
+
+def discover_base_ref(repo_root: Path) -> str:
+    configured = os.environ.get("SHOPIFY_LINT_BASE_REF")
+    if configured:
+        return configured
+
+    remote_head = run_command(
+        ["git", "symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"],
+        repo_root,
+    )
+    candidates = [remote_head.stdout.strip(), "origin/main", "main", "origin/master", "master"]
+    for candidate in candidates:
+        if not candidate:
+            continue
+        result = run_command(
+            ["git", "rev-parse", "--verify", "--quiet", f"{candidate}^{{commit}}"],
+            repo_root,
+        )
+        if result.returncode == 0:
+            return candidate
+
+    raise ShopifyLintError(
+        "Could not determine the base branch. Pass --base-ref or set "
+        "SHOPIFY_LINT_BASE_REF."
+    )
+
+
+def parse_nul_paths(output: str) -> set[str]:
+    return {path for path in output.split("\0") if path}
+
+
+def collect_changed_files(repo_root: Path, base_ref: str) -> set[str]:
+    merge_base = git_output(repo_root, "merge-base", "HEAD", base_ref).strip()
+    committed = git_output(
+        repo_root,
+        "diff",
+        "--name-only",
+        "--diff-filter=ACMR",
+        "-z",
+        f"{merge_base}..HEAD",
+    )
+    working_tree = git_output(
+        repo_root,
+        "diff",
+        "--name-only",
+        "--diff-filter=ACMR",
+        "-z",
+        "HEAD",
+    )
+    untracked = git_output(
+        repo_root,
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+        "-z",
+    )
+    return parse_nul_paths(committed) | parse_nul_paths(working_tree) | parse_nul_paths(
+        untracked
+    )
+
+
+def run_theme_check(
+    theme_path: Path, fail_level: str, config: Path | None
+) -> list[dict[str, Any]]:
+    command = [
+        "shopify",
+        "theme",
+        "check",
+        "--output",
+        "json",
+        "--path",
+        str(theme_path),
+        "--fail-level",
+        fail_level,
+    ]
+    if config:
+        command.extend(["--config", str(config)])
+
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError as error:
+        raise ShopifyLintError("Shopify CLI is not installed or is not on PATH.") from error
+
+    try:
+        reports = json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        detail = result.stderr.strip() or result.stdout.strip() or "no output"
+        raise ShopifyLintError(f"Shopify Theme Check failed: {detail}") from error
+
+    if not isinstance(reports, list):
+        raise ShopifyLintError("Shopify Theme Check returned an unexpected JSON shape.")
+    return reports
+
+
+def repo_relative_path(path: str, repo_root: Path) -> str | None:
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        candidate = repo_root / candidate
+    try:
+        return candidate.resolve().relative_to(repo_root.resolve()).as_posix()
+    except ValueError:
+        return None
+
+
+def filter_reports(
+    reports: list[dict[str, Any]], changed_files: set[str], repo_root: Path
+) -> list[dict[str, Any]]:
+    return [
+        report
+        for report in reports
+        if repo_relative_path(str(report.get("path", "")), repo_root) in changed_files
+    ]
+
+
+def normalized_reports(
+    reports: list[dict[str, Any]], repo_root: Path
+) -> list[dict[str, Any]]:
+    normalized = []
+    for report in reports:
+        item = dict(report)
+        item["path"] = repo_relative_path(str(report.get("path", "")), repo_root)
+        normalized.append(item)
+    return normalized
+
+
+def render_json(reports: list[dict[str, Any]], repo_root: Path) -> str:
+    return json.dumps(normalized_reports(reports, repo_root), indent=2)
+
+
+def render_text(reports: list[dict[str, Any]], repo_root: Path) -> str:
+    if not reports:
+        return "No Theme Check offenses found in files modified on this branch."
+
+    lines = []
+    offense_count = 0
+    for report in normalized_reports(reports, repo_root):
+        lines.append(str(report["path"]))
+        for offense in report.get("offenses", []):
+            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)
+            message = offense.get("message", "")
+            lines.append(f"  {severity} {check} {row}:{column} {message}".rstrip())
+        lines.append("")
+
+    file_label = "file" if len(reports) == 1 else "files"
+    offense_label = "offense" if offense_count == 1 else "offenses"
+    lines.append(
+        f"Theme Check found {offense_count} {offense_label} in "
+        f"{len(reports)} modified {file_label}."
+    )
+    return "\n".join(lines)
+
+
+def exit_code_for(reports: list[dict[str, Any]], fail_level: str) -> int:
+    threshold = SEVERITY_RANK[fail_level]
+    for report in reports:
+        for offense in report.get("offenses", []):
+            severity = str(offense.get("severity", "info")).lower()
+            if SEVERITY_RANK.get(severity, 0) <= threshold:
+                return 1
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Run Shopify Theme Check for files modified on the current branch."
+    )
+    parser.add_argument("--path", type=Path, default=Path.cwd(), help="Theme root path.")
+    parser.add_argument("--base-ref", help="Base branch or commit used for branch changes.")
+    parser.add_argument(
+        "--fail-level",
+        choices=tuple(SEVERITY_RANK),
+        default="error",
+        help="Minimum filtered severity that returns exit code 1.",
+    )
+    parser.add_argument("--config", type=Path, help="Theme Check config path.")
+    parser.add_argument(
+        "--format", choices=("text", "json"), default="text", help="Filtered output format."
+    )
+    return parser
+
+
+def main() -> int:
+    arguments = build_parser().parse_args()
+    theme_path = arguments.path.resolve()
+    try:
+        repo_root = find_repo_root(theme_path)
+        base_ref = arguments.base_ref or discover_base_ref(repo_root)
+        changed_files = collect_changed_files(repo_root, base_ref)
+        reports = run_theme_check(theme_path, arguments.fail_level, arguments.config)
+        filtered = filter_reports(reports, changed_files, repo_root)
+    except ShopifyLintError as error:
+        print(f"shopify-lint: {error}", file=sys.stderr)
+        return 2
+
+    output = (
+        render_json(filtered, repo_root)
+        if arguments.format == "json"
+        else render_text(filtered, repo_root)
+    )
+    print(output)
+    return exit_code_for(filtered, arguments.fail_level)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,137 @@
+"""Tests for the branch-scoped Shopify Theme Check runner."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT / "scripts"))
+
+import shopify_lint  # noqa: E402
+
+
+class ChangedFilesTests(unittest.TestCase):
+    def run_git(self, root: Path, *args: str) -> None:
+        subprocess.run(["git", *args], cwd=root, check=True, capture_output=True, text=True)
+
+    def test_collects_committed_staged_unstaged_and_untracked_files(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            self.run_git(root, "init", "-q", "-b", "main")
+            self.run_git(root, "config", "user.email", "test@example.com")
+            self.run_git(root, "config", "user.name", "Test User")
+
+            for name in ("committed.liquid", "staged.liquid", "unstaged.liquid"):
+                (root / name).write_text("initial\n")
+            self.run_git(root, "add", ".")
+            self.run_git(root, "commit", "-qm", "initial")
+            self.run_git(root, "switch", "-qc", "feature")
+
+            (root / "committed.liquid").write_text("branch change\n")
+            self.run_git(root, "add", "committed.liquid")
+            self.run_git(root, "commit", "-qm", "branch change")
+            (root / "staged.liquid").write_text("staged change\n")
+            self.run_git(root, "add", "staged.liquid")
+            (root / "unstaged.liquid").write_text("unstaged change\n")
+            (root / "untracked.liquid").write_text("untracked\n")
+
+            changed = shopify_lint.collect_changed_files(root, "main")
+
+            self.assertEqual(
+                changed,
+                {
+                    "committed.liquid",
+                    "staged.liquid",
+                    "unstaged.liquid",
+                    "untracked.liquid",
+                },
+            )
+
+
+class ThemeCheckTests(unittest.TestCase):
+    def test_runs_shopify_cli_with_json_output(self) -> None:
+        completed = subprocess.CompletedProcess([], 1, stdout="[]", stderr="")
+
+        with patch.object(shopify_lint.subprocess, "run", return_value=completed) as run:
+            result = shopify_lint.run_theme_check(Path("/theme"), "warning", None)
+
+        self.assertEqual(result, [])
+        run.assert_called_once_with(
+            [
+                "shopify",
+                "theme",
+                "check",
+                "--output",
+                "json",
+                "--path",
+                "/theme",
+                "--fail-level",
+                "warning",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+
+    def test_filters_reports_to_changed_repo_relative_paths(self) -> None:
+        root = Path("/repo")
+        reports = [
+            {
+                "path": "/repo/sections/td-changed.liquid",
+                "offenses": [{"check": "ChangedCheck", "severity": "error"}],
+            },
+            {
+                "path": "/repo/sections/unchanged.liquid",
+                "offenses": [{"check": "IgnoredCheck", "severity": "error"}],
+            },
+        ]
+
+        filtered = shopify_lint.filter_reports(
+            reports, {"sections/td-changed.liquid"}, root
+        )
+
+        self.assertEqual(filtered, [reports[0]])
+
+    def test_json_output_contains_only_changed_file_reports(self) -> None:
+        reports = [
+            {
+                "path": "/repo/sections/td-changed.liquid",
+                "offenses": [{"check": "LiquidHTMLSyntaxError", "severity": "error"}],
+            }
+        ]
+
+        rendered = shopify_lint.render_json(reports, Path("/repo"))
+
+        self.assertEqual(
+            json.loads(rendered),
+            [
+                {
+                    "path": "sections/td-changed.liquid",
+                    "offenses": [
+                        {"check": "LiquidHTMLSyntaxError", "severity": "error"}
+                    ],
+                }
+            ],
+        )
+
+    def test_fail_level_is_recomputed_from_filtered_offenses(self) -> None:
+        warning_report = [
+            {
+                "path": "changed.liquid",
+                "offenses": [{"check": "RemoteAsset", "severity": "warning"}],
+            }
+        ]
+
+        self.assertEqual(shopify_lint.exit_code_for(warning_report, "error"), 0)
+        self.assertEqual(shopify_lint.exit_code_for(warning_report, "warning"), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,14 @@
+extends:
+  - theme-check:recommended
+
+require:
+  - ./node_modules/theme-check-theory
+
+UnusedSectionSettings:
+  enabled: true
+  severity: warning
+
+UnguardedTextSetting:
+  enabled: true
+  severity: warning
+

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

@@ -0,0 +1,123 @@
+# theme-check-theory
+
+Theory Digital's custom [Shopify Theme Check](https://shopify.dev/docs/storefronts/themes/tools/theme-check)
+rules — house standards enforced on top of `theme-check:recommended`.
+
+Built for the TypeScript Theme Check engine (`@shopify/theme-check-common` v3)
+integrated into Shopify CLI. It is not compatible with the archived Ruby
+`Shopify/theme-check` project.
+
+## Checks
+
+| Code | Severity | What it catches |
+| --- | --- | --- |
+| `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`. |
+
+### UnusedSectionSettings
+
+This single-file check collects every `id` under `settings` and
+`blocks[].settings` in the schema, then collects static
+`section.settings.<id>` and `block.settings.<id>` references in the Liquid. It
+reports every declared setting that has no matching reference.
+
+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
+
+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.
+
+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.
+
+The setting types considered text-like are configurable with
+`textualSettingTypes`. The defaults are `text`, `textarea`, `richtext`,
+`inline_richtext`, `html`, `liquid`, and `url`.
+
+```yaml
+UnguardedTextSetting:
+  enabled: true
+  severity: warning
+  textualSettingTypes:
+    - text
+    - textarea
+    - image_picker
+```
+
+## Usage in a project
+
+Install the module as a development dependency:
+
+```bash
+npm install --save-dev theme-check-theory
+```
+
+Reference its CommonJS entry point from the project's `.theme-check.yml`:
+
+```yaml
+extends:
+  - theme-check:recommended
+
+require:
+  - ./node_modules/theme-check-theory
+
+UnusedSectionSettings:
+  enabled: true
+  severity: warning
+
+UnguardedTextSetting:
+  enabled: true
+  severity: warning
+```
+
+See [`.theme-check.example.yml`](.theme-check.example.yml) for a copyable
+configuration. The custom-check-only settings are also available in
+[`configs/recommended.yml`](configs/recommended.yml).
+
+Run Theme Check through Shopify CLI:
+
+```bash
+shopify theme check
+```
+
+## CI
+
+Start new checks at `warning` or `info` so they surface without blocking.
+Review the findings across existing themes, then promote them to `error` once
+the themes are clean.
+
+```yaml
+# .github/workflows/theme-check.yml
+- run: npm ci
+- run: npx shopify theme check --fail-level error
+```
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+Tests use `runLiquidCheck` and `check` from
+`@shopify/theme-check-common/dist/test/test-helper`, so Vitest exercises the
+real Theme Check parser and traversal rather than a mocked AST.
+
+## Adding a check
+
+1. Create `src/checks/<name>.ts` exporting a `LiquidCheckDefinition`.
+2. Add it to the `checks` array in `src/index.ts`.
+3. Add `src/checks/<name>.test.ts` with true-positive and false-positive cases.
+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.
+

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

@@ -0,0 +1,8 @@
+UnusedSectionSettings:
+  enabled: true
+  severity: warning
+
+UnguardedTextSetting:
+  enabled: true
+  severity: warning
+