td-ai-tools 1.2.11 → 1.3.2

package/skills/shopify-lint/stylelint-config-theory/src/liquid/mask.test.ts

@@ -0,0 +1,300 @@
+import { describe, expect, it } from 'vitest';
+
+import { maskLiquidStylesheet } 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>
+{% stylesheet %}
+  .td-hero { color: red; }
+{% endstylesheet %}
+`,
+  ],
+  [
+    'output interpolation',
+    `{% stylesheet %}
+  .td-hero { --td-gap: {{ section.settings.gap }}; }
+{% endstylesheet %}
+`,
+  ],
+  [
+    'whitespace control',
+    `{%- stylesheet -%}
+  .td-hero { color: red; }
+{%- endstylesheet -%}
+`,
+  ],
+  [
+    'control flow inside the block',
+    `{% stylesheet %}
+  {% if section.settings.wide %}
+  .td-hero { max-width: none; }
+  {% endif %}
+{% endstylesheet %}
+`,
+  ],
+  [
+    'comment tag inside the block',
+    `{% stylesheet %}
+  {% comment %} {{ not.real }} {% endcomment %}
+  .td-hero { color: red; }
+{% endstylesheet %}
+`,
+  ],
+  [
+    'raw tag inside the block',
+    `{% stylesheet %}
+  {% raw %}{{ literal }}{% endraw %}
+  .td-hero { color: red; }
+{% endstylesheet %}
+`,
+  ],
+  [
+    'nested at-rule',
+    `{% stylesheet %}
+  @media (min-width: 40em) {
+    .td-hero { color: red; }
+  }
+{% endstylesheet %}
+`,
+  ],
+  [
+    'markup around the block',
+    `{% schema %}{"name":"Hero"}{% endschema %}
+<div class="td-hero">{{ product.title }}</div>
+{% stylesheet %}
+  .td-hero { color: red; }
+{% endstylesheet %}
+{% javascript %}
+  console.log('hi');
+{% endjavascript %}
+`,
+  ],
+];
+
+describe('maskLiquidStylesheet position invariants', () => {
+  for (const [name, source] of SAMPLES) {
+    it(`preserves every character position: ${name}`, () => {
+      const masked = maskLiquidStylesheet(source);
+
+      expect(masked).not.toBeNull();
+      expect(masked).toHaveLength(source.length);
+
+      // Newlines must sit at exactly the same indices, or every reported line
+      // number would be wrong.
+      const newlineIndices = (text: string): number[] =>
+        [...text].flatMap((character, index) => (character === '\n' ? [index] : []));
+      expect(newlineIndices(masked!)).toEqual(newlineIndices(source));
+
+      // Nothing may be introduced that was not there: every non-space output
+      // character is either the source character, a blank, or the `0` that
+      // stands in for a Liquid output tag.
+      for (let index = 0; index < source.length; index += 1) {
+        const character = masked![index];
+        if (character !== ' ' && character !== '0') {
+          expect(character).toBe(source[index]);
+        }
+      }
+    });
+  }
+});
+
+describe('maskLiquidStylesheet', () => {
+  it('keeps the stylesheet body and blanks the surrounding markup', () => {
+    const source = `<div class="td-hero">Hello</div>
+{% stylesheet %}
+  .td-hero { color: red; }
+{% endstylesheet %}
+`;
+
+    const masked = maskLiquidStylesheet(source)!;
+    const lines = masked.split('\n');
+
+    expect(lines[0]!.trim()).toBe('');
+    expect(lines[1]!.trim()).toBe('');
+    expect(lines[2]).toBe('  .td-hero { color: red; }');
+    expect(lines[3]!.trim()).toBe('');
+  });
+
+  it('reports the body at its real line in the liquid file', () => {
+    const lines = [
+      '<div class="td-hero"></div>',
+      '{% stylesheet %}',
+      '  .td-hero { color: red; }',
+      '{% endstylesheet %}',
+      '',
+    ];
+
+    const masked = maskLiquidStylesheet(lines.join('\n'))!;
+
+    expect(masked.split('\n')[lines.indexOf('  .td-hero { color: red; }')]).toBe(
+      '  .td-hero { color: red; }',
+    );
+  });
+
+  it('masks Liquid output inside the body with a value placeholder', () => {
+    const output = '{{ settings.w }}';
+    const masked = maskLiquidStylesheet(
+      `{% stylesheet %}\n.a { width: ${output}; }\n{% endstylesheet %}\n`,
+    )!;
+
+    // `0` followed by blanks for the rest of the tag: a valid value token that
+    // occupies exactly the width of the Liquid it replaced.
+    expect(masked.split('\n')[1]).toBe(`.a { width: 0${' '.repeat(output.length - 1)}; }`);
+  });
+
+  it('masks Liquid tags inside the body', () => {
+    const masked = maskLiquidStylesheet(
+      '{% stylesheet %}\n{% if a %}.a { color: red; }{% endif %}\n{% endstylesheet %}\n',
+    )!;
+
+    expect(masked.split('\n')[1]!.trim()).toBe('.a { color: red; }');
+  });
+
+  it('leaves nested CSS blocks alone', () => {
+    const source = '{% stylesheet %}\n@media screen {{ .a { color: red; } }}\n{% endstylesheet %}\n';
+
+    // `{{ .a {` is not a Liquid output tag: its contents carry `{` and `;`.
+    expect(maskLiquidStylesheet(source)!.split('\n')[1]).toBe(
+      '@media screen {{ .a { color: red; } }}',
+    );
+  });
+
+  it('handles multiple blocks', () => {
+    const masked = maskLiquidStylesheet(
+      [
+        '{% stylesheet %}',
+        '.a { color: red; }',
+        '{% endstylesheet %}',
+        '<p>{{ product.title }}</p>',
+        '{% stylesheet %}',
+        '.b { color: blue; }',
+        '{% endstylesheet %}',
+        '',
+      ].join('\n'),
+    )!;
+    const lines = masked.split('\n');
+
+    expect(lines[1]).toBe('.a { color: red; }');
+    expect(lines[3]!.trim()).toBe('');
+    expect(lines[5]).toBe('.b { color: blue; }');
+  });
+
+  it('returns null when there is no stylesheet block', () => {
+    expect(maskLiquidStylesheet('<div class="td-hero"></div>\n')).toBeNull();
+  });
+
+  it('returns null when the block is never closed', () => {
+    expect(maskLiquidStylesheet('{% stylesheet %}\n.a { color: red; }\n')).toBeNull();
+  });
+
+  it('returns null for an empty block rather than reporting an empty source', () => {
+    expect(maskLiquidStylesheet('{% stylesheet %}\n\n{% endstylesheet %}\n')).toBeNull();
+    expect(maskLiquidStylesheet('{% stylesheet %}{% endstylesheet %}\n')).toBeNull();
+  });
+
+  it('returns null when the block only contains Liquid', () => {
+    // Everything maskable is masked away, so there is no CSS to report on.
+    expect(
+      maskLiquidStylesheet('{% stylesheet %}\n{% assign a = 1 %}\n{% endstylesheet %}\n'),
+    ).toBeNull();
+  });
+
+  it('skips a legacy scss block', () => {
+    expect(
+      maskLiquidStylesheet("{% stylesheet 'scss' %}\n.a { .b { color: red; } }\n{% endstylesheet %}\n"),
+    ).toBeNull();
+  });
+
+  it('lints the plain blocks of a file that also has an scss block', () => {
+    const masked = maskLiquidStylesheet(
+      [
+        "{% stylesheet 'scss' %}",
+        '.a { .b { color: red; } }',
+        '{% endstylesheet %}',
+        '{% stylesheet %}',
+        '.c { color: blue; }',
+        '{% endstylesheet %}',
+        '',
+      ].join('\n'),
+    )!;
+    const lines = masked.split('\n');
+
+    expect(lines[1]!.trim()).toBe('');
+    expect(lines[4]).toBe('.c { color: blue; }');
+  });
+
+  it('skips a block that is commented out', () => {
+    expect(
+      maskLiquidStylesheet(
+        [
+          '{% comment %}',
+          '{% stylesheet %}',
+          '.a { color: red; }',
+          '{% endstylesheet %}',
+          '{% endcomment %}',
+          '',
+        ].join('\n'),
+      ),
+    ).toBeNull();
+  });
+
+  it('skips a block inside a raw tag', () => {
+    expect(
+      maskLiquidStylesheet(
+        ['{% raw %}', '{% stylesheet %}', '.a { color: red; }', '{% endstylesheet %}', '{% endraw %}', ''].join(
+          '\n',
+        ),
+      ),
+    ).toBeNull();
+  });
+
+  it('still lints a live block alongside a commented-out one', () => {
+    const masked = maskLiquidStylesheet(
+      [
+        '{% comment %}',
+        '{% stylesheet %}',
+        '.old { color: red; }',
+        '{% endstylesheet %}',
+        '{% endcomment %}',
+        '{% stylesheet %}',
+        '.new { color: blue; }',
+        '{% endstylesheet %}',
+        '',
+      ].join('\n'),
+    )!;
+    const lines = masked.split('\n');
+
+    expect(lines[2]!.trim()).toBe('');
+    expect(lines[6]).toBe('.new { color: blue; }');
+  });
+
+  it('does not discard a block that contains a comment tag', () => {
+    const masked = maskLiquidStylesheet(
+      [
+        '{% stylesheet %}',
+        '{% comment %}note{% endcomment %}',
+        '.a { color: red; }',
+        '{% endstylesheet %}',
+        '',
+      ].join('\n'),
+    )!;
+    const lines = masked.split('\n');
+
+    expect(lines[1]!.trim()).toBe('');
+    expect(lines[2]).toBe('.a { color: red; }');
+  });
+
+  it('handles CRLF line endings without shifting columns', () => {
+    const source = '<div></div>\r\n{% stylesheet %}\r\n.a { color: red; }\r\n{% endstylesheet %}\r\n';
+    const masked = maskLiquidStylesheet(source)!;
+
+    expect(masked).toHaveLength(source.length);
+    // Only `\n` is preserved verbatim outside the body — a masked `\r` becomes
+    // a blank. That is enough: PostCSS counts lines by `\n`, and blanking
+    // cannot shift a column because the length is unchanged.
+    expect(masked.split('\n')[2]!.trimEnd()).toBe('.a { color: red; }');
+  });
+});

package/skills/shopify-lint/stylelint-config-theory/src/liquid/mask.ts

@@ -0,0 +1,203 @@
+/**
+ * Length-preserving masking of a Liquid file down to just its
+ * `{% stylesheet %}` content.
+ *
+ * The output is the same length as the input, with newlines at the same
+ * indices, so line and column numbers reported against the masked source are
+ * already correct for the original `.liquid` file. That identity mapping is
+ * the whole point: `bin/lint-css.mjs` hands the masked text to Stylelint as
+ * `code` with the real `.liquid` path as `codeFilename` and needs no offset
+ * arithmetic at all.
+ *
+ * This is the CSS twin of `eslint-plugin-theory/src/liquid/mask.ts`. The two
+ * are deliberately separate files: each bundled package installs and builds on
+ * its own, and neither depends on the other. Three behaviours differ, all
+ * because CSS blocks differ from JavaScript ones — see `maskLiquid` below.
+ */
+
+/**
+ * Matches a `{% stylesheet %}` … `{% endstylesheet %}` pair, capturing the
+ * opening tag's argument (if any) and the body.
+ *
+ * Current Shopify docs say the tag accepts no arguments, but the pre-2020
+ * `{% stylesheet 'scss' %}` form is still present in real themes, so the
+ * argument is matched in order to be recognised and skipped rather than
+ * silently mis-parsed as CSS.
+ */
+const STYLESHEET_BLOCK =
+  /(\{%-?\s*stylesheet\b([^%]*?)-?%\})([\s\S]*?)(\{%-?\s*endstylesheet\s*-?%\})/g;
+
+/** Liquid tags whose bodies are not Liquid and must be masked wholesale. */
+const RAW_CONTENT_TAG = /\{%-?\s*(comment|raw)\s*-?%\}[\s\S]*?\{%-?\s*end\1\s*-?%\}/g;
+
+/** A Liquid output tag, e.g. `{{ section.settings.accent | default: '#000' }}`. */
+const OUTPUT_TAG = /\{\{[\s\S]*?\}\}/g;
+
+/** Any remaining Liquid tag, e.g. `{% if … %}`, `{% assign … %}`, `{% liquid … %}`. */
+const LIQUID_TAG = /\{%[\s\S]*?%\}/g;
+
+/**
+ * Characters that never appear inside a Liquid output tag but do appear in the
+ * CSS constructs that can be mistaken for one — most importantly a nested
+ * block, `@media (width > 0) {{ … }}` is not valid CSS, but a rule whose last
+ * declaration is followed immediately by two closing braces is, and the
+ * mirrored `{{` case shows up in `@supports`/`@media` nesting.
+ *
+ * Theme Check's `StaticStylesheetAndJavascriptTags` applies no such guard, so it
+ * does report that construct as Liquid. Keeping the guard here means the block
+ * is still linted as the CSS it is.
+ */
+const NOT_LIQUID_OUTPUT = /[{};]/;
+
+interface Interval {
+  start: number;
+  end: number;
+}
+
+function blank(out: string[], start: number, end: number): void {
+  for (let index = start; index < end; index += 1) {
+    if (out[index] !== '\n') {
+      out[index] = ' ';
+    }
+  }
+}
+
+function copy(source: string, out: string[], start: number, end: number): void {
+  for (let index = start; index < end; index += 1) {
+    out[index] = source[index]!;
+  }
+}
+
+function overlaps(intervals: Interval[], start: number, end: number): boolean {
+  return intervals.some((interval) => start < interval.end && end > interval.start);
+}
+
+/**
+ * Whether an offset falls inside one of the intervals.
+ *
+ * Used to decide whether a `{% stylesheet %}` tag is itself commented out.
+ * Containment, not overlap, is the question: a block that *contains* a
+ * `{% comment %}` is still live CSS, and testing for overlap would throw it
+ * away.
+ */
+function contains(intervals: Interval[], offset: number): boolean {
+  return intervals.some((interval) => offset >= interval.start && offset < interval.end);
+}
+
+/** Every `{% comment %}` / `{% raw %}` region in the source, in order. */
+function rawContentRegions(source: string): Interval[] {
+  return [...source.matchAll(RAW_CONTENT_TAG)].map((match) => ({
+    start: match.index,
+    end: match.index + match[0].length,
+  }));
+}
+
+/**
+ * Mask the Liquid constructs inside one `{% stylesheet %}` body, in place.
+ *
+ * Order matters: `{% comment %}` and `{% raw %}` bodies are masked first so
+ * that Liquid-looking text inside them is not substituted a second time.
+ *
+ * Shopify does not render Liquid inside a `{% stylesheet %}` tag, so any
+ * interpolation found here is already broken theme code, and Theme Check's
+ * `StaticStylesheetAndJavascriptTags` reports it as an error. It is still masked
+ * rather than left in place, because a parse error at the first `{{` would hide
+ * every real offense in the rest of the block — the author gets the Liquid
+ * offense *and* the CSS offenses in one round.
+ */
+function maskLiquidInBody(source: string, out: string[], start: number, end: number): void {
+  const body = source.slice(start, end);
+  const rawRegions: Interval[] = [];
+
+  for (const match of body.matchAll(RAW_CONTENT_TAG)) {
+    const regionStart = start + match.index;
+    const regionEnd = regionStart + match[0].length;
+    blank(out, regionStart, regionEnd);
+    rawRegions.push({ start: regionStart, end: regionEnd });
+  }
+
+  for (const match of body.matchAll(OUTPUT_TAG)) {
+    const inner = match[0].slice(2, -2);
+    if (NOT_LIQUID_OUTPUT.test(inner)) {
+      // Almost certainly nested CSS blocks rather than Liquid output.
+      continue;
+    }
+    const regionStart = start + match.index;
+    const regionEnd = regionStart + match[0].length;
+    if (overlaps(rawRegions, regionStart, regionEnd)) {
+      continue;
+    }
+    blank(out, regionStart, regionEnd);
+    // A Liquid output can appear anywhere a CSS value component can, so stand
+    // it in with `0`: valid as a length, a number, or a bare value token. The
+    // substitution cannot be made correct for every property — `margin: 0  px`
+    // is what `margin: {{ s.gap }}px` becomes — so the value-shape rules may
+    // report on it. That is acceptable: the Liquid is itself an error, so the
+    // block has to be rewritten either way.
+    out[regionStart] = '0';
+  }
+
+  for (const match of body.matchAll(LIQUID_TAG)) {
+    const regionStart = start + match.index;
+    const regionEnd = regionStart + match[0].length;
+    if (overlaps(rawRegions, regionStart, regionEnd)) {
+      continue;
+    }
+    blank(out, regionStart, regionEnd);
+  }
+}
+
+/**
+ * Reduce a Liquid source to its `{% stylesheet %}` content, preserving every
+ * character position.
+ *
+ * Returns `null` when the file has nothing to lint, which lets the runner pass
+ * every modified `.liquid` file without reading it first. That is the case
+ * when:
+ *
+ * - there is no complete `{% stylesheet %}` … `{% endstylesheet %}` pair;
+ * - every such block sits inside a `{% comment %}` or `{% raw %}` region —
+ *   commented-out blocks are common mid-migration;
+ * - every block carries an argument (`{% stylesheet 'scss' %}`), whose body is
+ *   Sass rather than CSS and would only produce parse errors; or
+ * - every block's body is blank once masked, which would otherwise be reported
+ *   as `no-empty-source`.
+ */
+export function maskLiquidStylesheet(source: string): string | null {
+  // Indexed per UTF-16 code unit, not per code point, so that offsets stay
+  // aligned with `String.prototype.slice` and with the offsets Stylelint
+  // reports.
+  const out = new Array<string>(source.length);
+  for (let index = 0; index < source.length; index += 1) {
+    out[index] = source[index] === '\n' ? '\n' : ' ';
+  }
+
+  const rawRegions = rawContentRegions(source);
+  let found = false;
+
+  for (const match of source.matchAll(STYLESHEET_BLOCK)) {
+    const blockStart = match.index;
+    if (contains(rawRegions, blockStart)) {
+      // A commented-out or raw-quoted block is not live CSS.
+      continue;
+    }
+    if (match[2]!.trim() !== '') {
+      // `{% stylesheet 'scss' %}` — the body is Sass, not CSS.
+      continue;
+    }
+
+    const bodyStart = blockStart + match[1]!.length;
+    const bodyEnd = bodyStart + match[3]!.length;
+    copy(source, out, bodyStart, bodyEnd);
+    maskLiquidInBody(source, out, bodyStart, bodyEnd);
+    found = true;
+  }
+
+  if (!found) {
+    return null;
+  }
+
+  const masked = out.join('');
+  // An empty block is not an offense; `no-empty-source` would call it one.
+  return masked.trim() === '' ? null : masked;
+}

package/skills/shopify-lint/stylelint-config-theory/src/types/shared-configs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Type declarations for the two shared Stylelint configs.
+ *
+ * Neither package ships types, and no `@types/…` package exists for either, so
+ * `src/config.ts` would otherwise import them as `any` — which under `strict`
+ * is an error, and which would silently hide a change to their export shape.
+ *
+ * Both are ESM modules whose default export is a plain `Config`. `standard`
+ * additionally carries `extends: 'stylelint-config-recommended'` (a bare
+ * string, not an array); `createConfig` reads only `rules` from each, so that
+ * key is declared for accuracy rather than use.
+ */
+
+declare module 'stylelint-config-recommended' {
+  import type { Config } from 'stylelint';
+
+  const config: Config & { rules: NonNullable<Config['rules']> };
+  export default config;
+}
+
+declare module 'stylelint-config-standard' {
+  import type { Config } from 'stylelint';
+
+  const config: Config & { extends: string; rules: NonNullable<Config['rules']> };
+  export default config;
+}

package/skills/shopify-lint/stylelint-config-theory/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "sourceMap": true
+  },
+  "exclude": ["src/**/*.test.ts", "src/test-utils.ts"]
+}

package/skills/shopify-lint/stylelint-config-theory/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/skills/shopify-lint/stylelint-config-theory/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    coverage: {
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.test.ts', 'src/test-utils.ts'],
+    },
+  },
+});