td-ai-tools 1.2.9 → 1.2.10

package/skills/shopify-lint/eslint-plugin-theory/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "eslint-plugin-theory",
+  "version": "0.1.0",
+  "description": "Theory Digital's custom ESLint rules for Shopify theme JavaScript",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./config": "./dist/config.js"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "bin",
+    "eslint.config.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "shopify",
+    "eslint",
+    "eslintplugin",
+    "liquid",
+    "lint"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@eslint/js": "9.39.1",
+    "eslint": "9.39.1",
+    "globals": "16.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.0.15",
+    "typescript": "5.8.3",
+    "vitest": "3.2.7"
+  }
+}

package/skills/shopify-lint/eslint-plugin-theory/src/config.ts

@@ -0,0 +1,98 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import type { Linter } from 'eslint';
+
+import { plugin } from './index.js';
+
+/**
+ * Globals a Shopify storefront provides that are not part of the browser
+ * environment. Themes that expose more can extend this through a config passed
+ * with `SHOPIFY_LINT_ESLINT_CONFIG`.
+ */
+const SHOPIFY_GLOBALS: Linter.Globals = {
+  Shopify: 'readonly',
+  Swiper: 'readonly',
+  theme: 'readonly',
+};
+
+/**
+ * Severities for the bundled Theory rules.
+ *
+ * Rules that are purely syntactic, and whose violation is a real defect, are
+ * errors and so fail the branch lint at the default `--fail-level error`. The
+ * convention rules are warnings: they are reported but advisory, matching how
+ * the bundled Theme Check rules behave today.
+ */
+const THEORY_RULES: Linter.RulesRecord = {
+  'theory/guarded-custom-element-define': 'error',
+  'theory/no-unapproved-imports': 'error',
+  'theory/disconnected-callback-cleanup': 'warn',
+  'theory/no-class-selectors': 'warn',
+  'theory/centralize-selectors': 'warn',
+  'theory/require-jsdoc': 'warn',
+};
+
+/** Rules shipped but disabled by default; documented as opt-in. */
+const THEORY_OPTIONAL_RULES: Linter.RulesRecord = {
+  'theory/respect-reduced-motion': 'off',
+  'theory/aria-expanded-sync': 'off',
+  'theory/escape-to-close': 'off',
+  'theory/require-block-select-events': 'off',
+};
+
+export interface ConfigOptions {
+  /**
+   * How to parse standalone `.js` files. Theme assets are usually plain
+   * scripts, so the runner sniffs for top-level `import`/`export` and only
+   * uses `'module'` when it finds one.
+   */
+  sourceType?: 'script' | 'module';
+}
+
+export function createConfig(options: ConfigOptions = {}): Linter.Config[] {
+  const sourceType = options.sourceType ?? 'script';
+  const browserGlobals: Linter.Globals = { ...globals.browser, ...SHOPIFY_GLOBALS };
+
+  return [
+    {
+      ignores: ['**/node_modules/**', '**/*.min.js', '**/*.bundle.js'],
+    },
+    {
+      files: ['**/*.js', '**/*.mjs'],
+      languageOptions: {
+        ecmaVersion: 2022,
+        sourceType,
+        globals: browserGlobals,
+      },
+      plugins: { theory: plugin },
+      rules: {
+        ...js.configs.recommended.rules,
+        'no-empty': ['warn', { allowEmptyCatch: true }],
+        ...THEORY_OPTIONAL_RULES,
+        ...THEORY_RULES,
+      },
+    },
+    {
+      // JavaScript extracted from a `{% javascript %}` block. Shopify
+      // concatenates every theme block into one bundle, so identifiers defined
+      // in another file are legitimately global here.
+      files: ['**/*.liquid/*.js'],
+      languageOptions: {
+        ecmaVersion: 2022,
+        sourceType: 'script',
+        globals: browserGlobals,
+      },
+      rules: {
+        'no-undef': 'off',
+        'no-unused-vars': ['warn', { args: 'none', varsIgnorePattern: '^_' }],
+      },
+    },
+    {
+      files: ['**/*.liquid'],
+      plugins: { theory: plugin },
+      processor: 'theory/liquid',
+    },
+  ];
+}
+
+export default createConfig();

package/skills/shopify-lint/eslint-plugin-theory/src/index.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+
+import { plugin, rules } from './index.js';
+import { createConfig } from './config.js';
+
+const DEFAULT_ON = [
+  'guarded-custom-element-define',
+  'no-unapproved-imports',
+  'disconnected-callback-cleanup',
+  'no-class-selectors',
+  'centralize-selectors',
+  'require-jsdoc',
+];
+
+const DEFAULT_OFF = [
+  'respect-reduced-motion',
+  'aria-expanded-sync',
+  'escape-to-close',
+  'require-block-select-events',
+];
+
+describe('plugin registry', () => {
+  it('registers every rule exactly once', () => {
+    expect(Object.keys(rules).sort()).toEqual([...DEFAULT_ON, ...DEFAULT_OFF].sort());
+  });
+
+  it('exposes the liquid processor', () => {
+    expect(plugin.processors?.liquid).toBeDefined();
+  });
+
+  it('gives every rule a description and a schema', () => {
+    for (const [name, rule] of Object.entries(rules)) {
+      expect(rule.meta?.docs?.description, name).toBeTruthy();
+      expect(rule.meta?.schema, name).toBeDefined();
+      expect(Object.keys(rule.meta?.messages ?? {}).length, name).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('default config', () => {
+  const config = createConfig();
+  const jsBlock = config.find((entry) => entry.files?.includes('**/*.js'));
+  const configured = (jsBlock?.rules ?? {}) as Record<string, unknown>;
+
+  it('configures a severity for every registered rule', () => {
+    for (const name of Object.keys(rules)) {
+      expect(configured[`theory/${name}`], name).toBeDefined();
+    }
+  });
+
+  it('enables the high-confidence rules as errors', () => {
+    expect(configured['theory/guarded-custom-element-define']).toBe('error');
+    expect(configured['theory/no-unapproved-imports']).toBe('error');
+  });
+
+  it('keeps the convention rules advisory', () => {
+    expect(configured['theory/disconnected-callback-cleanup']).toBe('warn');
+    expect(configured['theory/no-class-selectors']).toBe('warn');
+    expect(configured['theory/centralize-selectors']).toBe('warn');
+    expect(configured['theory/require-jsdoc']).toBe('warn');
+  });
+
+  it('ships the heuristic rules disabled', () => {
+    for (const name of DEFAULT_OFF) {
+      expect(configured[`theory/${name}`], name).toBe('off');
+    }
+  });
+
+  it('turns no-undef off only for Liquid blocks', () => {
+    const liquidBlock = config.find((entry) => entry.files?.includes('**/*.liquid/*.js'));
+    expect(liquidBlock?.rules?.['no-undef']).toBe('off');
+    expect(configured['no-undef']).toBe('error');
+  });
+
+  it('wires the processor onto .liquid files', () => {
+    const liquidFiles = config.find((entry) => entry.files?.includes('**/*.liquid'));
+    expect(liquidFiles?.processor).toBe('theory/liquid');
+  });
+});

package/skills/shopify-lint/eslint-plugin-theory/src/index.ts

@@ -0,0 +1,50 @@
+import type { ESLint, Rule } from 'eslint';
+
+import { liquid } from './processors/liquid.js';
+import { centralizeSelectors } from './rules/centralize-selectors.js';
+import { disconnectedCallbackCleanup } from './rules/disconnected-callback-cleanup.js';
+import { guardedCustomElementDefine } from './rules/guarded-custom-element-define.js';
+import { noClassSelectors } from './rules/no-class-selectors.js';
+import { noUnapprovedImports } from './rules/no-unapproved-imports.js';
+import { requireJsdoc } from './rules/require-jsdoc.js';
+import {
+  ariaExpandedSync,
+  escapeToClose,
+  requireBlockSelectEvents,
+  respectReducedMotion,
+} from './rules/optional.js';
+
+export const rules: Record<string, Rule.RuleModule> = {
+  // Enabled by default.
+  'guarded-custom-element-define': guardedCustomElementDefine,
+  'no-unapproved-imports': noUnapprovedImports,
+  'disconnected-callback-cleanup': disconnectedCallbackCleanup,
+  'no-class-selectors': noClassSelectors,
+  'centralize-selectors': centralizeSelectors,
+  'require-jsdoc': requireJsdoc,
+  // Shipped disabled; see README.
+  'respect-reduced-motion': respectReducedMotion,
+  'aria-expanded-sync': ariaExpandedSync,
+  'escape-to-close': escapeToClose,
+  'require-block-select-events': requireBlockSelectEvents,
+};
+
+export const plugin: ESLint.Plugin = {
+  meta: {
+    name: 'eslint-plugin-theory',
+    version: '0.1.0',
+  },
+  rules,
+  processors: {
+    liquid,
+  },
+};
+
+export { liquid };
+export { maskLiquid } from './liquid/mask.js';
+
+// `createConfig` deliberately lives in ./config.js and is not re-exported
+// here: config.ts imports this module for the plugin object, and re-exporting
+// it would make that a cycle.
+
+export default plugin;

package/skills/shopify-lint/eslint-plugin-theory/src/integration.test.ts

@@ -0,0 +1,112 @@
+import { ESLint } from 'eslint';
+import { describe, expect, it } from 'vitest';
+
+import { createConfig } from './config.js';
+
+function lint(source: string, filePath: string) {
+  const eslint = new ESLint({
+    cwd: process.cwd(),
+    overrideConfigFile: true,
+    overrideConfig: createConfig({ sourceType: 'script' }),
+    errorOnUnmatchedPattern: false,
+    warnIgnored: false,
+  });
+  return eslint.lintText(source, { filePath });
+}
+
+/**
+ * Builds a source from an array of lines so the expected line number is
+ * derived rather than hand-counted.
+ */
+function sourceWith(lines: string[]) {
+  return { source: `${lines.join('\n')}\n`, lineOf: (needle: string) => lines.findIndex((line) => line.includes(needle)) + 1 };
+}
+
+describe('linting a .liquid file end to end', () => {
+  it('reports offenses at their real line in the .liquid file', async () => {
+    const { source, lineOf } = sourceWith([
+      '<div class="td-hero">',
+      '  <h2>{{ section.settings.heading }}</h2>',
+      '</div>',
+      '',
+      '{% javascript %}',
+      '  const cfg = {{ section.settings.cfg | json }};',
+      '  {% if section.settings.debug %}',
+      '  console.log(cfg);',
+      '  {% endif %}',
+      '  const dupe = { a: 1, a: 2 };',
+      '{% endjavascript %}',
+    ]);
+
+    const [result] = await lint(source, 'sections/td-hero.liquid');
+    const dupeKeys = result.messages.filter((message) => message.ruleId === 'no-dupe-keys');
+
+    expect(dupeKeys).toHaveLength(1);
+    expect(dupeKeys[0]?.line).toBe(lineOf('a: 2'));
+    expect(source.split('\n')[dupeKeys[0]!.line - 1]).toContain('a: 2');
+  });
+
+  it('maps offenses in a second block, after Liquid interpolation', async () => {
+    const { source, lineOf } = sourceWith([
+      '{% javascript %}',
+      '  const first = {{ section.settings.a | json }};',
+      '{% endjavascript %}',
+      '',
+      '<p>{{ product.title }}</p>',
+      '',
+      '{% javascript %}',
+      '  {% for block in section.blocks %}',
+      '  const second = { b: 1, b: 2 };',
+      '  {% endfor %}',
+      '{% endjavascript %}',
+    ]);
+
+    const [result] = await lint(source, 'sections/td-multi.liquid');
+    const dupeKeys = result.messages.filter((message) => message.ruleId === 'no-dupe-keys');
+
+    expect(dupeKeys).toHaveLength(1);
+    expect(dupeKeys[0]?.line).toBe(lineOf('b: 2'));
+  });
+
+  it('reports the correct column, not just the line', async () => {
+    const source = '{% javascript %}\nconst dupe = { a: 1, a: 2 };\n{% endjavascript %}\n';
+    const [result] = await lint(source, 'sections/td-column.liquid');
+    const [message] = result.messages.filter((entry) => entry.ruleId === 'no-dupe-keys');
+
+    // `a: 2` starts at index 21 of line 2, so column 22.
+    expect(message?.line).toBe(2);
+    expect(message?.column).toBe(22);
+  });
+
+  it('does not fire no-undef on Liquid-interpolated values', async () => {
+    const source = [
+      '{% javascript %}',
+      '  const total = {{ cart.item_count | json }};',
+      '  const name = "{{ product.title }}";',
+      '  render(total, name);',
+      '{% endjavascript %}',
+      '',
+    ].join('\n');
+
+    const [result] = await lint(source, 'sections/td-interp.liquid');
+    expect(result.messages.filter((message) => message.fatal)).toEqual([]);
+    expect(result.messages.filter((message) => message.ruleId === 'no-undef')).toEqual([]);
+  });
+
+  it('ignores markup outside the javascript block', async () => {
+    const source = '<script>var broken = ;</script>\n<div>{{ x }}</div>\n';
+    const [result] = await lint(source, 'sections/td-markup.liquid');
+    expect(result.messages).toEqual([]);
+  });
+
+  it('still lints a standalone .js file with no-undef enabled', async () => {
+    const [result] = await lint('missingHelper();\n', 'assets/td-scratch.js');
+    expect(result.messages.map((message) => message.ruleId)).toContain('no-undef');
+  });
+
+  it('allows browser and Shopify globals in a standalone .js file', async () => {
+    const source = 'document.addEventListener("click", () => { Shopify.doThing(); });\n';
+    const [result] = await lint(source, 'assets/td-globals.js');
+    expect(result.messages.filter((message) => message.ruleId === 'no-undef')).toEqual([]);
+  });
+});

package/skills/shopify-lint/eslint-plugin-theory/src/liquid/mask.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, it } from 'vitest';
+
+import { maskLiquid } from './mask.js';
+
+/** Realistic Liquid sources, used to assert the position-preserving invariants. */
+const SAMPLES: Array<[string, string]> = [
+  [
+    'simple block',
+    `<div class="td-hero">Hello</div>
+{% javascript %}
+  console.log('hi');
+{% endjavascript %}
+`,
+  ],
+  [
+    'output interpolation',
+    `{% javascript %}
+  const config = {{ section.settings.config | json }};
+  start(config);
+{% endjavascript %}
+`,
+  ],
+  [
+    'whitespace control',
+    `{%- javascript -%}
+  const flag = {{- section.settings.flag | json -}};
+{%- endjavascript -%}
+`,
+  ],
+  [
+    'control flow inside the block',
+    `{% javascript %}
+  {% if section.settings.autoplay %}
+  start();
+  {% endif %}
+{% endjavascript %}
+`,
+  ],
+  [
+    'comment tag inside the block',
+    `{% javascript %}
+  {% comment %} {{ not.real }} {% endcomment %}
+  run();
+{% endjavascript %}
+`,
+  ],
+  [
+    'raw tag inside the block',
+    `{% javascript %}
+  {% raw %}{{ literal }}{% endraw %}
+  run();
+{% endjavascript %}
+`,
+  ],
+  [
+    'multiple blocks',
+    `{% javascript %}
+  const a = 1;
+{% endjavascript %}
+<p>{{ product.title }}</p>
+{% javascript %}
+  const b = a + 1;
+{% endjavascript %}
+`,
+  ],
+  [
+    'multi-line output tag',
+    `{% javascript %}
+  const data = {{ section.settings.data
+    | json }};
+{% endjavascript %}
+`,
+  ],
+  [
+    'liquid tag block',
+    `{% javascript %}
+  {% liquid
+    assign x = 1
+    assign y = 2
+  %}
+  run();
+{% endjavascript %}
+`,
+  ],
+  [
+    'no javascript block',
+    `<div>{{ product.title }}</div>
+{% schema %}{}{% endschema %}
+`,
+  ],
+  [
+    'non-BMP characters outside the block',
+    `<p>🎉 launch</p>
+{% javascript %}
+  run();
+{% endjavascript %}
+`,
+  ],
+];
+
+function newlineIndices(value: string): number[] {
+  const indices: number[] = [];
+  for (let index = 0; index < value.length; index += 1) {
+    if (value[index] === '\n') {
+      indices.push(index);
+    }
+  }
+  return indices;
+}
+
+describe('maskLiquid invariants', () => {
+  it.each(SAMPLES)('preserves every position for %s', (_label, source) => {
+    const masked = maskLiquid(source);
+    if (masked === null) {
+      return;
+    }
+    expect(masked).toHaveLength(source.length);
+    expect(newlineIndices(masked)).toEqual(newlineIndices(source));
+  });
+
+  it.each(SAMPLES)('only ever blanks or substitutes for %s', (_label, source) => {
+    const masked = maskLiquid(source);
+    if (masked === null) {
+      return;
+    }
+    for (let index = 0; index < source.length; index += 1) {
+      const original = source[index];
+      const result = masked[index];
+      expect(result === original || result === ' ' || result === '0').toBe(true);
+    }
+  });
+});
+
+describe('maskLiquid', () => {
+  it('returns null when there is no javascript block', () => {
+    expect(maskLiquid('<div>{{ product.title }}</div>')).toBeNull();
+  });
+
+  it('returns null for an unterminated javascript block', () => {
+    expect(maskLiquid('{% javascript %}\n  run();\n')).toBeNull();
+  });
+
+  it('blanks everything outside the block, including the tags themselves', () => {
+    const masked = maskLiquid('<p>hi</p>{% javascript %}run();{% endjavascript %}<p>bye</p>');
+    // '<p>hi</p>' (9) + '{% javascript %}' (16), then the body, then
+    // '{% endjavascript %}' (19) + '<p>bye</p>' (10).
+    expect(masked).toBe(`${' '.repeat(25)}run();${' '.repeat(29)}`);
+  });
+
+  it('substitutes a Liquid output with a single 0 followed by spaces', () => {
+    const masked = maskLiquid('{% javascript %}const x = {{ a.b }};{% endjavascript %}');
+    // `{{ a.b }}` is nine characters: `0` plus eight spaces.
+    expect(masked).toContain(`const x = 0${' '.repeat(8)};`);
+  });
+
+  it('keeps a multi-line output tag on its original lines', () => {
+    const source = '{% javascript %}\nconst x = {{ a\n  | json }};\n{% endjavascript %}';
+    const masked = maskLiquid(source) ?? '';
+    const lines = masked.split('\n');
+    expect(lines[1]).toBe('const x = 0   ');
+    // `  | json }}` is the eleven-character tail of the output tag.
+    expect(lines[2]).toBe(`${' '.repeat(11)};`);
+  });
+
+  it('blanks a comment body rather than substituting the output inside it', () => {
+    const masked = maskLiquid('{% javascript %}{% comment %}{{ a }}{% endcomment %}run();{% endjavascript %}');
+    expect(masked).not.toContain('0');
+    expect(masked).toContain('run();');
+  });
+
+  it('blanks a raw body rather than substituting the output inside it', () => {
+    const masked = maskLiquid('{% javascript %}{% raw %}{{ a }}{% endraw %}run();{% endjavascript %}');
+    expect(masked).not.toContain('0');
+    expect(masked).toContain('run();');
+  });
+
+  it('leaves a nested JavaScript block alone', () => {
+    const source = '{% javascript %}if (a) {{ b(); }}{% endjavascript %}';
+    const masked = maskLiquid(source);
+    expect(masked).toContain('if (a) {{ b(); }}');
+  });
+
+  it('keeps content from every block in a multi-block file', () => {
+    const source = '{% javascript %}const a = 1;{% endjavascript %}\n{% javascript %}const b = 2;{% endjavascript %}';
+    const masked = maskLiquid(source) ?? '';
+    expect(masked).toContain('const a = 1;');
+    expect(masked).toContain('const b = 2;');
+  });
+
+  it('blanks Liquid control flow inside the block', () => {
+    const masked = maskLiquid('{% javascript %}{% if a %}run();{% endif %}{% endjavascript %}');
+    expect(masked).toContain('run();');
+    expect(masked).not.toContain('if a');
+  });
+});