td-ai-tools 1.2.8 → 1.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.2.8",
+  "version": "1.2.10",
   "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, including warnings for hard-coded…
+- `shopify-lint`: Run Shopify CLI Theme Check and Theory Digital's bundled Liquid and JavaScript rules together, linting…
 - `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,14 +1,14 @@
 ---
 name: shopify-lint
-version: 1.3.2
-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.
+version: 1.4.0
+description: Run Shopify CLI Theme Check and Theory Digital's bundled Liquid and JavaScript rules together, linting modified .js files and the JavaScript inside Liquid javascript blocks, 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, JavaScript, or theme changes, enforce Theory theme and vanilla JavaScript rules, or avoid surfacing pre-existing 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):
+The bundled `theme-check-theory` (Liquid checks) and `eslint-plugin-theory` (JavaScript rules) packages ship as TypeScript source only; their `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
@@ -17,12 +17,15 @@ 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. Setup replaces any existing file with the skill's current configuration so installs and updates cannot retain stale or incomplete settings.
-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.
+2. Runs `npm install && npm run build` inside `eslint-plugin-theory/`, producing the `dist/` that the JavaScript lint runner imports.
+3. Writes a `.theme-check.yml` at the project root wiring in the bundled checks. Setup replaces any existing file with the skill's current configuration so installs and updates cannot retain stale or incomplete settings.
+4. 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.
+No ESLint configuration is written to the project root, and the theme's own ESLint config is never consulted — the branch lint is a gate, so a theme must not be able to silently disable it. Override the rules per project with `SHOPIFY_LINT_ESLINT_CONFIG=<path>` pointing at a module that exports a `createConfig` function.
 
-Keep these dependencies inside `theme-check-theory/node_modules`; do not install Node dependencies at the theme root.
+The Stop hooks run this skill's branch-scoped lint before handoff at `--fail-level warning`, so **every reported offense blocks handoff, warnings included** — both the Theory Liquid checks and the Theory JavaScript rules. Only advisory `info` offenses do not block; that severity is reserved for JavaScript parse errors inside Liquid, which masking cannot always avoid and the agent cannot reliably fix. The hooks return modified-file offenses to the agent and allow handoff after three unsuccessful fix rounds. They require `jq`, `python3`, `node`, and Shopify CLI to be available when the hook runs. Directly running `scripts/setup.sh` performs the package builds and Theme Check configuration; use `td-ai-tools install --setup` or `td-ai-tools update --setup` to apply the shared hook manifest as well.
+
+Keep these dependencies inside each bundled package's `node_modules`; do not install Node dependencies at the theme root.
 
 ## Usage
 
@@ -32,15 +35,28 @@ 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. `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 script identifies files changed since the current branch's merge-base, adds staged, unstaged, and untracked files, then runs two 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.
+- **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.
+
+Standalone JavaScript is linted only when its **filename** contains `td-` (matched case-insensitively, anywhere in the name, so `td-globals.js` and `theme-td-utils.js` both qualify while `vendor.js` does not). This keeps vendored and merchant-authored assets from being reported against Theory conventions they were never written to. The match is on the filename alone — a `td-` directory does not opt its contents in — and `*.min.js` is always skipped.
+
+The filter does **not** apply to Liquid: `{% javascript %}` blocks are linted in every modified `.liquid` file regardless of its name, because that JavaScript is Theory's either way.
+
+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.
+
+`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.
+
+Liquid interpolation is masked out before the JavaScript is parsed. Control flow that straddles a JavaScript syntax boundary can defeat that, so parse errors inside `.liquid` are reported at `info` — visible, but never failing a run that cannot reasonably be fixed.
 
 ## 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.
+1. Confirm `shopify`, `python3`, and `node` (>= 20) are available.
+2. Run the bundled script instead of calling `shopify theme check` or `eslint` 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, Node, or JSON-processing error.
+4. Fix every reported issue, warnings included, and rerun until the command passes. Run with `--fail-level warning` to match what the Stop hooks enforce. Do not fix offenses in untouched files unless the user expands the scope.
+5. Keep bundled-package dependencies inside `theme-check-theory/node_modules` and `eslint-plugin-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:
 
@@ -48,6 +64,8 @@ The default base is `origin/HEAD`, then `origin/main`, `main`, `origin/master`,
 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.
+Set `SHOPIFY_LINT_BASE_REF` for the same override in automation. Use `--format json` for machine-readable filtered output. The CLI still defaults to `--fail-level error`; the Stop hooks pass `--fail-level warning` explicitly, and `--fail-level info` additionally fails on advisory Liquid parse errors. When passing `--config <path>`, preserve the bundled package's `require` entry or the Theory checks will not load.
+
+Pass `--skip-js` (or set `SHOPIFY_LINT_SKIP_JS=1`) to report Theme Check offenses only — useful when the JavaScript toolchain is unavailable. Node is not spawned at all when no `.js`, `.mjs`, or `.liquid` file changed.
 
 Do not use Theme Check auto-correction through this workflow because it can modify untouched files before filtering.

package/skills/shopify-lint/eslint-plugin-theory/README.md

@@ -0,0 +1,198 @@
+# eslint-plugin-theory
+
+Theory Digital's custom ESLint rules for Shopify theme JavaScript, plus a
+processor that lints the JavaScript inside Liquid `{% javascript %}` blocks.
+
+It is bundled with the `shopify-lint` skill and is normally run through that
+skill's branch-scoped runner rather than directly. Like `theme-check-theory`,
+it ships as TypeScript source: `npm install && npm run build` produces the
+`dist/` that `bin/lint-js.mjs` imports.
+
+## Rules
+
+| Rule | Default | Catches |
+| --- | --- | --- |
+| `theory/guarded-custom-element-define` | **error** | `customElements.define` without a `customElements.get` guard |
+| `theory/no-unapproved-imports` | **error** | Third-party JavaScript outside the allowlist (Swiper, Embla) |
+| `theory/disconnected-callback-cleanup` | warning | Listeners, timers, and observers never torn down |
+| `theory/no-class-selectors` | warning | Classes used as JavaScript behaviour hooks |
+| `theory/centralize-selectors` | warning | The same selector literal repeated inline |
+| `theory/require-jsdoc` | warning | Named classes and functions without JSDoc documentation and explicit types |
+| `theory/respect-reduced-motion` | off | Motion with no `prefers-reduced-motion` check |
+| `theory/aria-expanded-sync` | off | Disclosure state toggled without `aria-expanded` |
+| `theory/escape-to-close` | off | Dismissible components that ignore Escape |
+| `theory/require-block-select-events` | off | Block-aware components missing the editor hooks |
+
+Errors fail the branch lint at its default `--fail-level error`; warnings are
+reported but advisory, matching how the bundled Theme Check rules behave.
+
+### theory/guarded-custom-element-define
+
+Re-registering a tag name throws, and that exception takes out every later
+script on the page. Shopify renders section files more than once — in the theme
+editor, and through section rendering — so an unguarded define is a real defect.
+
+Accepted guards, all matched against the same tag expression as the define
+(a string literal and a constant holding one are both handled):
+
+```js
+if (!customElements.get('td-hero')) { customElements.define('td-hero', TdHero); }
+customElements.get('td-hero') || customElements.define('td-hero', TdHero);
+if (customElements.get('td-hero')) return;   // earlier in the same scope
+```
+
+**Blind spot:** a guard whose tag expression is written differently from the
+define's (`customElements.get(TAG)` guarding `define('td-hero', …)`) is not
+recognised and will be reported.
+
+### theory/no-unapproved-imports
+
+Theory themes are vanilla JavaScript; Swiper and Embla are the sanctioned
+libraries. Relative and absolute specifiers are always allowed — they are the
+theme's own files. Covers `import`, dynamic `import()`, `export … from`, and
+`require()`.
+
+The default allowlist is `['swiper', 'embla-carousel*']`. A trailing `*`
+matches a family of sibling packages, which Embla needs because it ships each
+plugin as its own package (`embla-carousel-autoplay`, `embla-carousel-fade`, …)
+rather than as subpaths of one package the way Swiper does. Scoping is
+respected: `@someone/embla-carousel-extra` is a different package and is still
+reported.
+
+Extend the allowlist per project with `{ allow: ['gsap'] }`, or
+`{ allow: ['@acme/*'] }` for a family.
+
+**Blind spot:** a non-literal specifier (`import(name)`) cannot be resolved
+statically and is skipped.
+
+### theory/disconnected-callback-cleanup
+
+Applies to custom-element-shaped classes only: those extending something
+ending in `Element`, or defining a `connectedCallback`.
+
+Matching is by **category**, never by the identity of a particular listener or
+handle — identity matching is what makes this class of rule unusable in
+practice. Registering in a helper method counts, and a single
+`AbortController.abort()` satisfies the listener category wholesale.
+
+| Registered | Satisfied by |
+| --- | --- |
+| `addEventListener` (without `{ once: true }`) | `removeEventListener`, or any `.abort()` |
+| `setInterval` | `clearInterval` |
+| `setTimeout` (only when the handle is stored) | `clearTimeout` |
+| `requestAnimationFrame` (only when the handle is stored) | `cancelAnimationFrame` |
+| `new *Observer` | `.disconnect()` or `.unobserve()` |
+
+**Blind spot:** it verifies that a category is torn down, not that *every*
+instance of it is. A component removing one of two listeners passes.
+
+### theory/no-class-selectors
+
+Merchants edit markup, so a class rename in the theme editor silently breaks
+JavaScript that queried it. Behaviour hooks belong on `data-td-*` attributes;
+classes are for visual state via `classList`.
+
+Checks literal selectors passed to `querySelector`, `querySelectorAll`,
+`closest`, and `matches`, always flags `getElementsByClassName`, and looks
+inside objects named `SELECTORS`/`selectors` so moving a class selector into a
+constant does not hide it. The selector is scanned rather than regex-matched,
+so a dot inside an attribute value (`[data-src=".jpg"]`) or a CSS-escaped dot
+is not mistaken for a class.
+
+Record an approved exception with a comment on or above the line, as the
+ruleset's exception policy requires:
+
+```js
+/* td-selector-exception: Swiper owns this markup */
+this.querySelector('.swiper-slide');
+```
+
+**Blind spot:** selectors built at runtime are skipped entirely.
+
+### theory/centralize-selectors
+
+Reports a selector literal used inline `threshold` times or more (default `2`),
+excluding the first use. The threshold is what makes the rule shippable: a
+selector used once is perfectly readable, and flagging it would be noise. A
+call that takes a reference to a constant is already centralized and never
+counted.
+
+### theory/require-jsdoc
+
+Requires a JSDoc comment immediately above every named class, function,
+function-valued variable, and non-constructor class method. Function comments
+must include a typed `@param {Type}` for every parameter and a typed
+`@returns {Type}` (use `{void}` when the function has no return value).
+
+Anonymous callbacks are intentionally excluded: documenting event handlers and
+array callbacks inline would add noise without improving their public contract.
+
+### Opt-in rules
+
+The four default-off rules each encode a real Theory standard that is not
+reliably observable from the JavaScript AST: motion frequently lives in CSS,
+ARIA is often set by a separate render step, Escape is often handled by a
+parent or natively by `<dialog>`, and "block-dependent" is a property of the
+Liquid template rather than the script. Enable them deliberately, per project,
+through `SHOPIFY_LINT_ESLINT_CONFIG`.
+
+## Liquid handling
+
+`.liquid` files run through the `theory/liquid` processor. Rather than
+extracting each `{% javascript %}` block, it returns the **whole file with
+every non-JavaScript character replaced by a space**, newlines untouched.
+Positions are therefore unchanged, and remapping offenses back to the `.liquid`
+file is the identity function — there is no offset arithmetic to get wrong.
+
+Inside a block:
+
+| Construct | Becomes |
+| --- | --- |
+| `{% comment %}` / `{% raw %}` bodies | spaces |
+| `{{ … }}` | `0` followed by spaces |
+| `{% … %}` | spaces |
+
+`0` stands in for a Liquid output because it is valid wherever an output can
+appear — a value, an argument, a property key, a template substitution — and,
+being a literal, it introduces no identifier for `no-undef` to fire on.
+`no-undef` is off for Liquid blocks anyway: Shopify concatenates every theme
+block into one bundle, so identifiers defined in another file are legitimately
+global.
+
+A file with no `{% javascript %}` block produces no blocks at all and is
+skipped.
+
+**Known limit.** Liquid control flow that straddles a JavaScript syntax
+boundary cannot mask into valid JavaScript:
+
+```liquid
+{% if a %}function f() {{% else %}function g() {{% endif %}}
+```
+
+That produces a genuine parse error. The branch runner reports parse errors
+found in `.liquid` at `info` severity, with a note that the position may be
+approximate, so a masking limitation can never fail a run the author has no
+reasonable way to fix. Parse errors in standalone `.js` files remain errors.
+
+Note also that a rule reporting "at the top of the program" reports at line 1
+of the `.liquid` file rather than at the block.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Adding a rule
+
+1. Create `src/rules/<name>.ts` exporting a `Rule.RuleModule`.
+2. Register it in the `rules` map in `src/index.ts`.
+3. Add `src/rules/<name>.test.ts` with `RuleTester` cases. Include *valid*
+   cases for every false positive you can think of — those are the cases that
+   decide whether the rule is usable.
+4. Give it a severity in `THEORY_RULES` (or `THEORY_OPTIONAL_RULES`) in
+   `src/config.ts`. `src/index.test.ts` fails if a registered rule has no
+   configured severity.
+5. Document it in the table and in a section above, including its blind spots.

package/skills/shopify-lint/eslint-plugin-theory/bin/lint-js.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * Lint runner spawned by scripts/shopify_lint.py.
+ *
+ * Reads `{"cwd": "<theme root>", "files": ["<absolute path>", ...]}` on stdin
+ * and writes ESLint's native results array to stdout.
+ *
+ * Exit codes:
+ *   0  results were produced (however many problems they contain)
+ *   1  the lint could not run
+ *
+ * Lint problems never change the exit code — the branch runner owns the
+ * fail-level policy.
+ */
+
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+const MODULE_SYNTAX = /^\s*(?:import|export)\s/m;
+
+function fail(message) {
+  process.stderr.write(`theory js lint: ${message}\n`);
+  process.exit(1);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+/**
+ * Theme assets are usually plain scripts, but some themes ship ES modules.
+ * Parsing a script as a module (or the reverse) produces spurious syntax
+ * errors, so files are partitioned and linted by two ESLint instances.
+ */
+function usesModuleSyntax(file) {
+  if (file.endsWith('.mjs')) {
+    return true;
+  }
+  if (!file.endsWith('.js')) {
+    return false;
+  }
+  try {
+    return MODULE_SYNTAX.test(readFileSync(file, 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+async function loadConfig(createConfig) {
+  const override = process.env.SHOPIFY_LINT_ESLINT_CONFIG;
+  if (!override) {
+    return createConfig;
+  }
+  const imported = await import(pathToFileURL(override).href);
+  const custom = imported.createConfig ?? imported.default;
+  if (typeof custom !== 'function') {
+    fail(`config at ${override} must export a createConfig function or a default function.`);
+  }
+  return custom;
+}
+
+async function main() {
+  let payload;
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch (error) {
+    fail(`could not parse the request on stdin: ${error.message}`);
+  }
+
+  const files = Array.isArray(payload?.files) ? payload.files : [];
+  if (files.length === 0) {
+    process.stdout.write('[]');
+    return;
+  }
+
+  let ESLint;
+  let createConfig;
+  try {
+    ({ ESLint } = await import('eslint'));
+    ({ createConfig } = await import('../dist/config.js'));
+  } catch (error) {
+    fail(
+      'dependencies are not installed or the package is not built. ' +
+        `Run: bash <skill>/scripts/setup.sh (${error.message})`,
+    );
+  }
+
+  const buildConfig = await loadConfig(createConfig);
+  const cwd = payload.cwd ?? process.cwd();
+
+  const moduleFiles = [];
+  const scriptFiles = [];
+  for (const file of files) {
+    (usesModuleSyntax(file) ? moduleFiles : scriptFiles).push(file);
+  }
+
+  const results = [];
+  for (const [sourceType, group] of [
+    ['script', scriptFiles],
+    ['module', moduleFiles],
+  ]) {
+    if (group.length === 0) {
+      continue;
+    }
+    const eslint = new ESLint({
+      cwd,
+      // Never consult the theme's own ESLint configuration: the branch lint is
+      // a gate, so a theme must not be able to silently disable it.
+      overrideConfigFile: true,
+      overrideConfig: buildConfig({ sourceType }),
+      errorOnUnmatchedPattern: false,
+      warnIgnored: false,
+    });
+    results.push(...(await eslint.lintFiles(group)));
+  }
+
+  process.stdout.write(JSON.stringify(results));
+}
+
+main().catch((error) => {
+  fail(error?.stack ?? String(error));
+});

package/skills/shopify-lint/eslint-plugin-theory/eslint.config.mjs

@@ -0,0 +1,4 @@
+// Flat config entry point for editors and for `npx eslint` inside a theme.
+// The branch runner (bin/lint-js.mjs) imports `createConfig` directly instead,
+// so that it can select the source type per file.
+export { default } from './dist/config.js';