td-ai-tools 1.2.0 → 1.2.2

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
+