td-ai-tools 1.2.11 → 1.3.2

package/skills/shopify-pre-pr/scripts/vendor_change_audit.py

@@ -0,0 +1,540 @@
+#!/usr/bin/env python3
+"""Audit branch changes to vendor files for TD CHANGE delimiter coverage.
+
+A vendor file is any changed file whose basename does not contain the custom
+prefix (`td-` by default). Every modification to such a file must sit inside a
+pair of TD CHANGE delimiter comments. This script reports, per file, which
+changed line ranges are already inside a delimiter block at any nesting depth
+and which still need to be wrapped.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+
+
+DEFAULT_BASE_CANDIDATES = ("main", "origin/main", "master", "origin/master")
+
+START_TEXT = "------------TD CHANGE-----------"
+END_TEXT = "----------END TD CHANGE---------"
+
+# `END` is checked before `START`, because an end marker also matches the start
+# pattern. Separators are loose so hand-typed variants still count as coverage.
+END_MARKER = re.compile(r"END[\s_-]*TD[\s_-]*CHANGE", re.IGNORECASE)
+START_MARKER = re.compile(r"TD[\s_-]*CHANGE", re.IGNORECASE)
+
+HUNK_HEADER = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@")
+
+# Comment styles keyed by extension. `None` means the format cannot carry
+# comments at all, so the change has to be documented instead of delimited.
+LINE_COMMENT = "line"
+BLOCK_COMMENT = "block"
+
+COMMENT_STYLES: dict[str, dict[str, str] | None] = {
+    ".liquid": {"kind": BLOCK_COMMENT, "open": "{% comment %}", "close": "{% endcomment %}", "language": "liquid"},
+    ".js": {"kind": LINE_COMMENT, "open": "//", "language": "javascript"},
+    ".mjs": {"kind": LINE_COMMENT, "open": "//", "language": "javascript"},
+    ".cjs": {"kind": LINE_COMMENT, "open": "//", "language": "javascript"},
+    ".ts": {"kind": LINE_COMMENT, "open": "//", "language": "typescript"},
+    ".css": {"kind": BLOCK_COMMENT, "open": "/*", "close": "*/", "language": "css"},
+    ".scss": {"kind": LINE_COMMENT, "open": "//", "language": "scss"},
+    ".sass": {"kind": LINE_COMMENT, "open": "//", "language": "sass"},
+    ".html": {"kind": BLOCK_COMMENT, "open": "<!--", "close": "-->", "language": "html"},
+    ".svg": {"kind": BLOCK_COMMENT, "open": "<!--", "close": "-->", "language": "svg"},
+    ".xml": {"kind": BLOCK_COMMENT, "open": "<!--", "close": "-->", "language": "xml"},
+    ".md": {"kind": BLOCK_COMMENT, "open": "<!--", "close": "-->", "language": "markdown"},
+    ".yml": {"kind": LINE_COMMENT, "open": "#", "language": "yaml"},
+    ".yaml": {"kind": LINE_COMMENT, "open": "#", "language": "yaml"},
+    ".sh": {"kind": LINE_COMMENT, "open": "#", "language": "shell"},
+    ".json": None,
+    ".jsonc": None,
+}
+
+# Regions inside a `.liquid` file that use a different comment syntax than the
+# surrounding Liquid markup, or that cannot be commented at all.
+LIQUID_REGIONS = (
+    ("schema", re.compile(r"\{%-?\s*schema\s*-?%\}"), re.compile(r"\{%-?\s*endschema\s*-?%\}"), None),
+    ("javascript", re.compile(r"\{%-?\s*javascript\s*-?%\}"), re.compile(r"\{%-?\s*endjavascript\s*-?%\}"), ".js"),
+    ("stylesheet", re.compile(r"\{%-?\s*stylesheet[^%]*-?%\}"), re.compile(r"\{%-?\s*endstylesheet\s*-?%\}"), ".css"),
+    ("script tag", re.compile(r"<script(?![^>]*\bsrc=)[^>]*>"), re.compile(r"</script>"), ".js"),
+    ("style tag", re.compile(r"<style[^>]*>"), re.compile(r"</style>"), ".css"),
+)
+
+# Paths that are project tooling or documentation rather than theme vendor code.
+IGNORED_PREFIXES = (".agents/", ".claude/", ".codex/", ".github/", ".vscode/", "docs/", "node_modules/")
+IGNORED_BASENAMES = ("package-lock.json", "yarn.lock", "pnpm-lock.yaml", ".gitignore", "README.md", "AGENTS.md", "CLAUDE.md")
+
+
+def run_git(*args: str) -> str:
+    completed = subprocess.run(
+        ["git", *args],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
+def ref_exists(ref: str) -> bool:
+    completed = subprocess.run(
+        ["git", "rev-parse", "--verify", f"{ref}^{{commit}}"],
+        capture_output=True,
+        text=True,
+    )
+    return completed.returncode == 0
+
+
+def resolve_base_ref(explicit_base: str | None) -> str:
+    if explicit_base:
+        if not ref_exists(explicit_base):
+            raise SystemExit(f"Base ref not found: {explicit_base}")
+        return explicit_base
+
+    for candidate in DEFAULT_BASE_CANDIDATES:
+        if ref_exists(candidate):
+            return candidate
+
+    searched = ", ".join(DEFAULT_BASE_CANDIDATES)
+    raise SystemExit(f"No base ref found. Tried: {searched}")
+
+
+def is_ignored(path: str) -> bool:
+    if path.startswith(IGNORED_PREFIXES):
+        return True
+    return os.path.basename(path) in IGNORED_BASENAMES
+
+
+def is_custom(path: str, prefixes: tuple[str, ...]) -> bool:
+    """A file is custom (not vendor) when its basename contains a custom prefix."""
+    basename = os.path.basename(path)
+    return any(prefix in basename for prefix in prefixes)
+
+
+def comment_style(path: str) -> dict[str, str] | None:
+    _, ext = os.path.splitext(path)
+    return COMMENT_STYLES.get(ext.lower())
+
+
+def has_known_extension(path: str) -> bool:
+    _, ext = os.path.splitext(path)
+    return ext.lower() in COMMENT_STYLES
+
+
+def delimiters(style: dict[str, str]) -> tuple[str, str]:
+    """Render the start/end delimiter lines for a comment style."""
+    if style["kind"] == LINE_COMMENT:
+        return f"{style['open']} {START_TEXT}", f"{style['open']} {END_TEXT}"
+    return (
+        f"{style['open']} {START_TEXT} {style['close']}",
+        f"{style['open']} {END_TEXT} {style['close']}",
+    )
+
+
+def parse_hunk_ranges(diff_output: str) -> list[tuple[int, int]]:
+    """Extract post-image line ranges from a `-U0` diff.
+
+    A pure deletion (`+c,0`) is reported as the single line `c`, the line the
+    removed content used to follow, so its surroundings are still checked for
+    delimiter coverage.
+    """
+    ranges: list[tuple[int, int]] = []
+    for line in diff_output.splitlines():
+        match = HUNK_HEADER.match(line)
+        if not match:
+            continue
+        start = int(match.group(1))
+        count = 1 if match.group(2) is None else int(match.group(2))
+        if count == 0:
+            ranges.append((max(start, 1), max(start, 1)))
+            continue
+        ranges.append((start, start + count - 1))
+    return ranges
+
+
+def scan_markers(lines: list[str]) -> dict[str, object]:
+    """Walk a file and record which lines sit inside a TD CHANGE block.
+
+    Nesting is tracked with a depth counter, so a change enclosed by an outer
+    block counts as covered even when an inner block sits beside it. Marker
+    lines themselves count as covered.
+    """
+    covered: set[int] = set()
+    blocks: list[dict[str, int]] = []
+    unclosed: list[int] = []
+    unmatched_ends: list[int] = []
+    open_starts: list[int] = []
+
+    for index, line in enumerate(lines, start=1):
+        if END_MARKER.search(line):
+            if open_starts:
+                start_line = open_starts.pop()
+                blocks.append({"start": start_line, "end": index, "depth": len(open_starts) + 1})
+            else:
+                unmatched_ends.append(index)
+            covered.add(index)
+            continue
+
+        if START_MARKER.search(line):
+            open_starts.append(index)
+            covered.add(index)
+            continue
+
+        if open_starts:
+            covered.add(index)
+
+    unclosed = sorted(open_starts)
+    return {
+        "covered": covered,
+        "blocks": sorted(blocks, key=lambda block: block["start"]),
+        "unclosed_starts": unclosed,
+        "unmatched_ends": unmatched_ends,
+    }
+
+
+def scan_liquid_regions(lines: list[str]) -> list[dict[str, object]]:
+    """Locate embedded regions in a Liquid file that need a different comment syntax."""
+    regions: list[dict[str, object]] = []
+    open_region: dict[str, object] | None = None
+
+    for index, line in enumerate(lines, start=1):
+        if open_region is not None:
+            if open_region["_end"].search(line):  # type: ignore[union-attr]
+                open_region["end"] = index
+                del open_region["_end"]
+                regions.append(open_region)
+                open_region = None
+            continue
+
+        for name, start_pattern, end_pattern, ext in LIQUID_REGIONS:
+            if not start_pattern.search(line):
+                continue
+            if end_pattern.search(line):
+                # Opened and closed on one line; nothing spans into later lines.
+                regions.append({"name": name, "start": index, "end": index, "extension": ext})
+            else:
+                open_region = {"name": name, "start": index, "end": 0, "extension": ext, "_end": end_pattern}
+            break
+
+    if open_region is not None:
+        open_region["end"] = len(lines)
+        del open_region["_end"]
+        regions.append(open_region)
+
+    return regions
+
+
+def region_for_range(regions: list[dict[str, object]], start: int, end: int) -> dict[str, object] | None:
+    for region in regions:
+        if start <= region["end"] and end >= region["start"]:  # type: ignore[operator]
+            return region
+    return None
+
+
+def coverage_for_range(covered: set[int], start: int, end: int) -> str:
+    total = end - start + 1
+    inside = sum(1 for line in range(start, end + 1) if line in covered)
+    if inside == 0:
+        return "uncovered"
+    if inside == total:
+        return "covered"
+    return "partial"
+
+
+def audit_file(path: str, merge_base: str, prefixes: tuple[str, ...], status: str) -> dict[str, object]:
+    """Classify one changed file and, for vendor edits, check delimiter coverage."""
+    entry: dict[str, object] = {"path": path, "status": status}
+
+    if is_ignored(path):
+        entry["category"] = "ignored"
+        return entry
+
+    if is_custom(path, prefixes):
+        entry["category"] = "custom"
+        return entry
+
+    if status == "D":
+        entry["category"] = "vendor_deleted"
+        return entry
+
+    if status == "A":
+        entry["category"] = "vendor_added"
+        return entry
+
+    style = comment_style(path)
+    if style is None:
+        entry["category"] = "not_delimitable"
+        entry["reason"] = (
+            "JSON does not support comments" if has_known_extension(path) else "unrecognized file type"
+        )
+        return entry
+
+    entry["category"] = "vendor_modified"
+    entry["language"] = style["language"]
+    start_delimiter, end_delimiter = delimiters(style)
+    entry["start_delimiter"] = start_delimiter
+    entry["end_delimiter"] = end_delimiter
+
+    try:
+        with open(path, encoding="utf-8") as handle:
+            lines = handle.read().splitlines()
+    except (OSError, UnicodeDecodeError) as error:
+        entry["category"] = "unreadable"
+        entry["reason"] = str(error)
+        return entry
+
+    diff = run_git("diff", "-U0", merge_base, "--", path)
+    ranges = parse_hunk_ranges(diff)
+    markers = scan_markers(lines)
+    covered: set[int] = markers["covered"]  # type: ignore[assignment]
+    regions = scan_liquid_regions(lines) if path.lower().endswith(".liquid") else []
+
+    hunks: list[dict[str, object]] = []
+    for start, end in ranges:
+        hunk: dict[str, object] = {
+            "start": start,
+            "end": end,
+            "coverage": coverage_for_range(covered, start, end),
+        }
+        region = region_for_range(regions, start, end)
+        if region is not None:
+            hunk["region"] = region["name"]
+            region_extension = region["extension"]
+            if region_extension is None:
+                hunk["delimitable"] = False
+            else:
+                region_style = COMMENT_STYLES[region_extension]
+                assert region_style is not None
+                region_start, region_end = delimiters(region_style)
+                hunk["start_delimiter"] = region_start
+                hunk["end_delimiter"] = region_end
+        hunks.append(hunk)
+
+    entry["hunks"] = hunks
+    entry["blocks"] = markers["blocks"]
+    entry["unclosed_starts"] = markers["unclosed_starts"]
+    entry["unmatched_ends"] = markers["unmatched_ends"]
+    # A hunk in a region that cannot carry comments is never actionable here, so
+    # it does not count as needing delimiters — it has to be documented instead.
+    entry["needs_delimiters"] = any(
+        hunk["coverage"] != "covered" and hunk.get("delimitable") is not False for hunk in hunks
+    )
+    entry["undelimitable_hunks"] = [
+        hunk for hunk in hunks if hunk["coverage"] != "covered" and hunk.get("delimitable") is False
+    ]
+    entry["malformed"] = bool(markers["unclosed_starts"] or markers["unmatched_ends"])
+    return entry
+
+
+def parse_name_status(output: str) -> list[dict[str, str]]:
+    files: list[dict[str, str]] = []
+    for line in output.splitlines():
+        if not line:
+            continue
+        parts = line.split("\t")
+        status = parts[0]
+
+        if status.startswith("R") and len(parts) >= 3:
+            files.append({"status": "M", "path": parts[2], "old_path": parts[1]})
+            continue
+
+        path = parts[1] if len(parts) > 1 else ""
+        files.append({"status": status[0], "path": path, "old_path": ""})
+    return files
+
+
+def build_report(base_ref: str, prefixes: tuple[str, ...], paths: list[str]) -> dict[str, object]:
+    current_branch = run_git("branch", "--show-current")
+    merge_base = run_git("merge-base", base_ref, "HEAD")
+
+    diff_args = ["diff", "--name-status", "--find-renames", merge_base]
+    if paths:
+        diff_args += ["--", *paths]
+    changed = parse_name_status(run_git(*diff_args))
+
+    untracked_args = ["ls-files", "--others", "--exclude-standard"]
+    if paths:
+        untracked_args += ["--", *paths]
+    tracked_paths = {item["path"] for item in changed}
+    for path in run_git(*untracked_args).splitlines():
+        if path and path not in tracked_paths:
+            changed.append({"status": "A", "path": path, "old_path": ""})
+
+    entries = [audit_file(item["path"], merge_base, prefixes, item["status"]) for item in changed]
+
+    return {
+        "current_branch": current_branch,
+        "base_ref": base_ref,
+        "merge_base": merge_base,
+        "custom_prefixes": list(prefixes),
+        "files": entries,
+    }
+
+
+def describe_hunk(hunk: dict[str, object]) -> str:
+    start, end = hunk["start"], hunk["end"]
+    location = f"{start}" if start == end else f"{start}-{end}"
+    if hunk.get("region"):
+        location += f" (inside {hunk['region']})"
+    if hunk.get("delimitable") is False:
+        location += " — cannot be commented"
+    if hunk["coverage"] == "partial":
+        location += " — partially delimited"
+    return location
+
+
+def print_markdown(report: dict[str, object]) -> None:
+    files: list[dict[str, object]] = report["files"]  # type: ignore[assignment]
+    vendor = [entry for entry in files if entry["category"] == "vendor_modified"]
+    needs = [entry for entry in vendor if entry.get("needs_delimiters")]
+    clean = [
+        entry
+        for entry in vendor
+        if not entry.get("needs_delimiters") and not entry.get("undelimitable_hunks")
+    ]
+    malformed = [entry for entry in vendor if entry.get("malformed")]
+    undelimitable = [entry for entry in files if entry["category"] == "not_delimitable"]
+    undelimitable_hunks = [entry for entry in vendor if entry.get("undelimitable_hunks")]
+    added = [entry for entry in files if entry["category"] == "vendor_added"]
+    deleted = [entry for entry in files if entry["category"] == "vendor_deleted"]
+    unreadable = [entry for entry in files if entry["category"] == "unreadable"]
+
+    print("# Vendor Change Audit")
+    print()
+    print(f"- Current branch: `{report['current_branch']}`")
+    print(f"- Base ref: `{report['base_ref']}`")
+    print(f"- Merge base: `{report['merge_base']}`")
+    print(f"- Custom prefixes: {', '.join(f'`{prefix}`' for prefix in report['custom_prefixes'])}")
+    print(f"- Vendor files modified: {len(vendor)} ({len(needs)} needing delimiters)")
+    print()
+
+    if needs:
+        print("## Needs delimiters")
+        print()
+        for entry in needs:
+            print(f"### `{entry['path']}` ({entry['language']})")
+            print()
+            print(f"- Start: `{entry['start_delimiter']}`")
+            print(f"- End: `{entry['end_delimiter']}`")
+            open_hunks = [
+                hunk
+                for hunk in entry["hunks"]  # type: ignore[union-attr]
+                if hunk["coverage"] != "covered" and hunk.get("delimitable") is not False
+            ]
+            for hunk in open_hunks:
+                extra = ""
+                if hunk.get("start_delimiter"):
+                    extra = f" — use `{hunk['start_delimiter']}` / `{hunk['end_delimiter']}`"
+                print(f"- Lines {describe_hunk(hunk)}{extra}")
+            print()
+
+    if clean:
+        print("## Already delimited")
+        print()
+        for entry in clean:
+            count = len(entry["hunks"])  # type: ignore[arg-type]
+            blocks = len(entry["blocks"])  # type: ignore[arg-type]
+            print(f"- `{entry['path']}` — {count} changed hunk(s) inside {blocks} TD CHANGE block(s)")
+        print()
+
+    if malformed:
+        print("## Malformed markers")
+        print()
+        for entry in malformed:
+            for line in entry["unclosed_starts"]:  # type: ignore[union-attr]
+                print(f"- `{entry['path']}:{line}` — TD CHANGE opened without an END TD CHANGE")
+            for line in entry["unmatched_ends"]:  # type: ignore[union-attr]
+                print(f"- `{entry['path']}:{line}` — END TD CHANGE without a matching TD CHANGE")
+        print()
+
+    if undelimitable or undelimitable_hunks:
+        print("## Cannot be delimited")
+        print()
+        print("Delimiters are impossible here. Document these in `docs/changes.md` with reapply steps.")
+        print()
+        for entry in undelimitable:
+            print(f"- `{entry['path']}` — {entry['reason']}")
+        for entry in undelimitable_hunks:
+            for hunk in entry["undelimitable_hunks"]:  # type: ignore[union-attr]
+                location = hunk["start"] if hunk["start"] == hunk["end"] else f"{hunk['start']}-{hunk['end']}"
+                print(f"- `{entry['path']}` lines {location} — inside {hunk['region']}")
+        print()
+
+    if added or deleted:
+        print("## Other vendor-path changes")
+        print()
+        for entry in added:
+            print(f"- `{entry['path']}` — new file without a custom prefix; rename it or justify it")
+        for entry in deleted:
+            print(f"- `{entry['path']}` — vendor file deleted; confirm this is intentional")
+        print()
+
+    if unreadable:
+        print("## Unreadable")
+        print()
+        for entry in unreadable:
+            print(f"- `{entry['path']}` — {entry['reason']}")
+        print()
+
+    if not vendor and not undelimitable and not added and not deleted:
+        print("No vendor files changed on this branch.")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Audit vendor file changes on this branch for TD CHANGE delimiter coverage."
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        help="Optional path filters. Defaults to every changed file on the branch.",
+    )
+    parser.add_argument(
+        "--base",
+        help="Explicit base ref to compare against. Defaults to main/origin-main or master/origin-master fallback.",
+    )
+    parser.add_argument(
+        "--custom-prefix",
+        action="append",
+        default=None,
+        help="Filename substring marking a file as custom rather than vendor. Repeatable. Defaults to `td-`.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("markdown", "json"),
+        default="markdown",
+        help="Output format.",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Exit 1 when any vendor change is missing delimiters.",
+    )
+    args = parser.parse_args()
+
+    prefixes = tuple(args.custom_prefix or ["td-"])
+    base_ref = resolve_base_ref(args.base)
+    report = build_report(base_ref, prefixes, args.paths)
+
+    if args.format == "json":
+        print(json.dumps(report, indent=2))
+    else:
+        print_markdown(report)
+
+    if args.strict:
+        files: list[dict[str, object]] = report["files"]  # type: ignore[assignment]
+        if any(entry.get("needs_delimiters") or entry.get("malformed") for entry in files):
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except subprocess.CalledProcessError as error:
+        sys.stderr.write(error.stderr or str(error))
+        raise SystemExit(error.returncode)

package/skills/record-changes/SKILL.md

@@ -1,76 +0,0 @@
----
-name: record-changes
-version: 1.0.0
-description: Update `docs/changes.md` by summarizing the current branch against the primary development branch. Use when a developer asks to record branch changes, document theme customizations, refresh the project change log, or write a branch summary into `docs/changes.md`. Prefer comparing against `main`, but fall back to `origin/main`, `master`, or `origin/master` when the repository does not have a local `main` branch.
----
-
-# Record Changes
-
-Update `docs/changes.md` from the current branch diff. Preserve the existing document structure and add a concise, human-readable entry for the branch.
-
-## Workflow
-
-### 1. Collect Branch Context
-
-Run the bundled script first:
-
-```bash
-python3 .agents/skills/record-changes/scripts/branch_diff_context.py
-```
-
-If the developer specifies another comparison branch, pass it explicitly:
-
-```bash
-python3 .agents/skills/record-changes/scripts/branch_diff_context.py --base release/x.y
-```
-
-Read the existing `docs/changes.md` before editing so the new entry matches the current ordering, tone, and section layout.
-
-### 2. Inspect the Actual Code Changes
-
-Use the script output to identify changed files, then inspect the relevant diffs and file contents with `git diff` and targeted file reads.
-
-Prioritize:
-
-- User-facing behavior changes
-- CMS setting/schema changes
-- CSS or markup changes that affect rendering
-- Renamed files and vendor-theme hotspots
-
-Do not summarize the `docs/changes.md` edit itself as part of the branch work. If the branch contains unrelated skill or tooling files, either omit them from the changelog entry or separate them clearly when they are relevant to the project's maintenance history.
-
-### 3. Write the Changelog Entry
-
-Add a new entry near the top of `docs/changes.md`, directly under the intro, unless the file already uses another ordering convention.
-
-Follow the existing pattern:
-
-- `## <short title>`
-- `**Date:** YYYY-MM-DD`
-- `### Purpose`
-- `### Files changed`
-- `### Upgrade impact`
-- `### Notes`
-
-Guidelines:
-
-- Make the title describe the feature or fix, not the branch name.
-- Write `Purpose` in plain language with outcome-focused bullets.
-- Use the `Files changed` table to explain why each file matters.
-- Call out non-`td-` theme or vendor files in a separate subsection when in a Shopify project.
-- Mention renamed files explicitly.
-- Keep `Upgrade impact` brief and concrete.
-- Use `Notes` for implementation details, edge cases, or assumptions.
-
-### 4. Verify Before Finishing
-
-Before wrapping up:
-
-- Re-read the new markdown entry in context.
-- Confirm every listed file appears in the diff.
-- Confirm the documented behavior matches the code, not just the branch name.
-- Mention any uncertainty if the diff is too broad to summarize with high confidence.
-
-## Resource
-
-- `scripts/branch_diff_context.py`: Resolve the best available base branch and print a branch summary with file statuses and line counts.

package/skills/record-changes/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-    display_name: 'Record Changes'
-    short_description: 'Summarize branch changes into docs/changes.md'
-    default_prompt: 'Use $record-changes to compare this branch to main and update docs/changes.md.'