td-ai-tools 1.2.11 → 1.3.2

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

@@ -0,0 +1,47 @@
+{
+  "name": "stylelint-config-theory",
+  "version": "0.1.0",
+  "description": "Theory Digital's Stylelint configuration for Shopify theme CSS",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./config": "./dist/config.js"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "bin",
+    ".stylelintignore",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "shopify",
+    "stylelint",
+    "stylelint-config",
+    "liquid",
+    "css",
+    "lint"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "dependencies": {
+    "stylelint": "17.14.1",
+    "stylelint-config-recommended": "18.0.0",
+    "stylelint-config-standard": "40.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.0.15",
+    "typescript": "5.8.3",
+    "vitest": "3.2.7"
+  }
+}

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

@@ -0,0 +1,31 @@
+import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+import { describe, expect, it } from 'vitest';
+
+const run = promisify(execFile);
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+describe('the published build', () => {
+  // `scripts/setup.sh` runs `npm run build` for this package, so a type error
+  // here breaks setup for every consumer of the shopify-lint skill.
+  it('typechecks under the build config', async () => {
+    const result = await run('npx', ['tsc', '-p', 'tsconfig.build.json', '--noEmit'], {
+      cwd: packageRoot,
+    }).catch((error: { stdout?: string; stderr?: string }) => error);
+
+    expect([result.stdout, result.stderr].filter(Boolean).join('\n')).toBe('');
+  }, 120_000);
+
+  // bin/lint-css.mjs imports from dist/, so the entry points it needs must
+  // survive any reshuffle of the source tree.
+  it('exposes the entry points the runner imports', async () => {
+    const config = await import(resolve(packageRoot, 'dist/config.js'));
+    const index = await import(resolve(packageRoot, 'dist/index.js'));
+
+    expect(typeof config.createConfig).toBe('function');
+    expect(typeof index.maskLiquidStylesheet).toBe('function');
+  });
+});

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

@@ -0,0 +1,150 @@
+import recommended from 'stylelint-config-recommended';
+import standard from 'stylelint-config-standard';
+import { describe, expect, it } from 'vitest';
+
+import { createConfig } from './config.js';
+
+const RECOMMENDED_RULES = Object.keys(recommended.rules ?? {});
+const STANDARD_ONLY_RULES = Object.keys(standard.rules ?? {}).filter(
+  (name) => !RECOMMENDED_RULES.includes(name),
+);
+
+/** The severity Stylelint would resolve for a rule, given the config. */
+function severityOf(config: ReturnType<typeof createConfig>, name: string): string | undefined {
+  const settings = config.rules?.[name];
+  if (settings === null || settings === undefined) {
+    return undefined;
+  }
+  const secondary = Array.isArray(settings) ? settings[1] : undefined;
+  const explicit = (secondary as { severity?: string } | undefined)?.severity;
+  return explicit ?? (config.defaultSeverity as string | undefined);
+}
+
+describe('createConfig', () => {
+  it('covers every rule from both shared configs', () => {
+    const config = createConfig();
+
+    for (const name of [...RECOMMENDED_RULES, ...STANDARD_ONLY_RULES]) {
+      expect(config.rules).toHaveProperty(name);
+    }
+  });
+
+  it('adds no rules the shared configs do not define', () => {
+    const known = new Set([...RECOMMENDED_RULES, ...STANDARD_ONLY_RULES]);
+
+    expect(Object.keys(createConfig().rules ?? {}).filter((name) => !known.has(name))).toEqual([]);
+  });
+
+  it('sanity-checks the split the severity policy depends on', () => {
+    // If upstream ever reshapes these configs, the grading below is meaningless
+    // without this holding.
+    expect(RECOMMENDED_RULES.length).toBeGreaterThan(30);
+    expect(STANDARD_ONLY_RULES.length).toBeGreaterThan(30);
+    expect(RECOMMENDED_RULES.filter((name) => STANDARD_ONLY_RULES.includes(name))).toEqual([]);
+  });
+
+  it('grades the correctness layer as errors', () => {
+    const config = createConfig();
+    const overridden = new Set(['no-descending-specificity']);
+
+    for (const name of RECOMMENDED_RULES) {
+      if (overridden.has(name)) {
+        continue;
+      }
+      expect(severityOf(config, name), name).toBe('error');
+    }
+  });
+
+  it('grades the convention layer as warnings', () => {
+    const config = createConfig();
+
+    for (const name of STANDARD_ONLY_RULES) {
+      const severity = severityOf(config, name);
+      // `undefined` means the rule is deliberately disabled by an override.
+      if (severity === undefined) {
+        expect(config.rules?.[name]).toBeNull();
+        continue;
+      }
+      expect(severity, name).toBe('warning');
+    }
+  });
+
+  it('defaults unspecified severities to warning', () => {
+    expect(createConfig().defaultSeverity).toBe('warning');
+  });
+
+  it('preserves the options of a promoted rule', () => {
+    // `selector-type-no-unknown` ships as `[true, { ignore: ['custom-elements'] }]`
+    // and must keep that option, or every `<product-card>` would be reported.
+    expect(createConfig().rules?.['selector-type-no-unknown']).toEqual([
+      true,
+      { ignore: ['custom-elements'], severity: 'error' },
+    ]);
+  });
+
+  it('widens a bare primary value when promoting it', () => {
+    expect(createConfig().rules?.['block-no-empty']).toEqual([true, { severity: 'error' }]);
+  });
+
+  it('keeps a message function intact', () => {
+    // A promoted rule with a `message` function must keep it callable: the
+    // config is used in-process and must never be JSON round-tripped.
+    const settings = createConfig().rules?.['custom-media-pattern'];
+    const secondary = Array.isArray(settings) ? (settings[1] as { message?: unknown }) : undefined;
+
+    expect(typeof secondary?.message).toBe('function');
+  });
+
+  it('disables the naming-pattern rules pending a Theory convention', () => {
+    const config = createConfig();
+
+    for (const name of [
+      'selector-class-pattern',
+      'selector-id-pattern',
+      'custom-property-pattern',
+      'keyframes-name-pattern',
+    ]) {
+      expect(config.rules?.[name], name).toBeNull();
+    }
+  });
+
+  it('demotes no-descending-specificity to a warning', () => {
+    expect(severityOf(createConfig(), 'no-descending-specificity')).toBe('warning');
+  });
+
+  it('keeps the value-shape rules enabled', () => {
+    // These were once disabled for `{% stylesheet %}` blocks, where a masked
+    // Liquid output stands in as a value. Liquid there is now reported as an
+    // error by Theme Check's `StaticStylesheetAndJavascriptTags`, so there is
+    // no correct theme
+    // code left for the relaxation to protect, and a `.liquid` block is graded
+    // exactly as a `.css` file is.
+    const config = createConfig();
+
+    for (const name of [
+      'declaration-property-value-no-unknown',
+      'declaration-property-value-keyword-no-deprecated',
+      'at-rule-prelude-no-invalid',
+      'media-query-no-invalid',
+      'media-feature-name-value-no-unknown',
+      'syntax-string-no-invalid',
+      'function-calc-no-unspaced-operator',
+      'no-empty-source',
+    ]) {
+      expect(severityOf(config, name), name).toBe('error');
+    }
+    expect(severityOf(config, 'function-url-quotes')).toBe('warning');
+  });
+
+  it('takes no options, so every source is graded the same way', () => {
+    // The signature is the contract a `SHOPIFY_LINT_STYLELINT_CONFIG` override
+    // has to match; an argument passed by an older caller must not change the
+    // result.
+    expect(createConfig.length).toBe(0);
+    expect(
+      (createConfig as (options?: unknown) => ReturnType<typeof createConfig>)({
+        source: 'liquid',
+      }),
+    ).toEqual(createConfig());
+  });
+});

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

@@ -0,0 +1,109 @@
+import recommended from 'stylelint-config-recommended';
+import standard from 'stylelint-config-standard';
+import type { Config } from 'stylelint';
+
+type RuleSettings = Config['rules'] extends Record<string, infer Value> | undefined
+  ? Value
+  : never;
+
+/**
+ * Severities for the upstream Stylelint rules.
+ *
+ * The two shared configs split cleanly along the line this skill already draws
+ * for JavaScript in `eslint-plugin-theory/src/config.ts`: rules whose violation
+ * is a real defect are errors and so fail the branch lint at the default
+ * `--fail-level error`, while the convention rules are warnings — reported but
+ * advisory, matching how the bundled Theme Check rules behave.
+ *
+ * `stylelint-config-recommended` is the correctness layer: unknown properties
+ * and at-rules, duplicate declarations, invalid values, empty blocks. Those are
+ * errors. `stylelint-config-standard` adds notational conventions on top —
+ * `color-function-notation`, `length-zero-no-unit`, the kebab-case patterns —
+ * and those are warnings.
+ *
+ * Deriving the split from `Object.keys(recommended.rules)` rather than listing
+ * it here means it tracks upstream: a rule promoted into the recommended config
+ * becomes an error on the next dependency bump without anyone editing this file.
+ */
+const CORRECTNESS_RULES = new Set(Object.keys(recommended.rules ?? {}));
+
+/**
+ * Deliberate departures from the shared configs, applied to every source.
+ *
+ * Anything set to `null` here is shipped disabled and documented in the README
+ * as opt-in, mirroring `THEORY_OPTIONAL_RULES` on the JavaScript side.
+ */
+const THEORY_OVERRIDES: Record<string, RuleSettings> = {
+  // Standard's default pattern is `^([a-z][a-z0-9]*)(-[a-z0-9]+)*$`, which
+  // rejects the BEM-ish names Theory writes (`td-card__title--active`).
+  // Re-enable with a Theory-specific pattern once that naming is written down.
+  'selector-class-pattern': null,
+  'selector-id-pattern': null,
+  'custom-property-pattern': null,
+  'keyframes-name-pattern': null,
+  // In the recommended config, so it would otherwise be an error. Too noisy on
+  // real theme CSS to block a handoff over.
+  'no-descending-specificity': [true, { severity: 'warning' }],
+};
+
+/**
+ * Stamp a severity onto one rule's settings without losing its options.
+ *
+ * Several `stylelint-config-standard` rules carry a `message` **function** in
+ * their secondary options, so the secondary object has to be merged into rather
+ * than replaced. A rule whose primary value is not already an array is widened
+ * into the `[primary, secondary]` form, which is how Stylelint expects a
+ * severity to be expressed.
+ */
+function withSeverity(settings: RuleSettings, severity: 'error' | 'warning'): RuleSettings {
+  if (settings === null || settings === undefined) {
+    return settings;
+  }
+  if (Array.isArray(settings)) {
+    const [primary, secondary] = settings;
+    if (primary === null) {
+      return settings;
+    }
+    return [primary, { ...(secondary as object | undefined), severity }];
+  }
+  return [settings, { severity }];
+}
+
+/**
+ * Build the configuration.
+ *
+ * One config serves both standalone `.css` and the CSS masked out of a
+ * `{% stylesheet %}` block. There used to be a relaxed variant for Liquid,
+ * because a masked interpolation stands in as a value and the rules that
+ * inspect the shape of a value fired on it. Liquid inside `{% stylesheet %}` is
+ * now an offense in its own right — Theme Check's
+ * `StaticStylesheetAndJavascriptTags` reports it as an error — so a value built
+ * out of a placeholder can only appear in a block that is already failing the
+ * lint, and there is nothing left for the relaxation to protect.
+ *
+ * It takes no options, and is still a function so that a project override
+ * passed through `SHOPIFY_LINT_STYLELINT_CONFIG` keeps the same shape.
+ */
+export function createConfig(): Config {
+  const merged: Record<string, RuleSettings> = {
+    ...(recommended.rules as Record<string, RuleSettings>),
+    ...(standard.rules as Record<string, RuleSettings>),
+  };
+
+  const rules: Record<string, RuleSettings> = {};
+  for (const [name, settings] of Object.entries(merged)) {
+    rules[name] = CORRECTNESS_RULES.has(name) ? withSeverity(settings, 'error') : settings;
+  }
+
+  Object.assign(rules, THEORY_OVERRIDES);
+
+  return {
+    // Everything the standard config adds on top of the correctness layer is a
+    // convention, so warning is the right floor; the correctness rules are
+    // promoted to error individually above.
+    defaultSeverity: 'warning',
+    rules,
+  };
+}
+
+export default createConfig();

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

@@ -0,0 +1,15 @@
+/**
+ * Theory Digital's Stylelint configuration for Shopify theme CSS.
+ *
+ * The package ships no custom rules yet: the branch lint runs the upstream
+ * `stylelint-config-standard` set, graded by `./config.js`. When Theory CSS
+ * conventions are written down, add a `src/rules/` directory and a `plugin`
+ * export here — `createConfig` is the only place the wiring would change, and
+ * the runner and the Python orchestrator would not need touching. See README.
+ */
+
+export { maskLiquidStylesheet } from './liquid/mask.js';
+
+// `createConfig` deliberately lives in ./config.js and is not re-exported here,
+// matching eslint-plugin-theory: once this module gains a plugin object that
+// config.ts imports, re-exporting it would make that a cycle.

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

@@ -0,0 +1,187 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import stylelint from 'stylelint';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { createConfig } from './config.js';
+import { maskLiquidStylesheet } from './liquid/mask.js';
+
+/**
+ * Lint a source the way `bin/lint-css.mjs` does, so these tests exercise the
+ * real Stylelint pipeline rather than the config object alone.
+ */
+async function lint(
+  code: string,
+  codeFilename: string,
+  cwd: string,
+): Promise<stylelint.Warning[]> {
+  const result = await stylelint.lint({
+    code,
+    codeFilename,
+    config: createConfig(),
+    cwd,
+    ignorePath: join(import.meta.dirname, '..', '.stylelintignore'),
+    disableDefaultIgnores: true,
+    quietDeprecationWarnings: true,
+  });
+
+  expect(result.results).toHaveLength(1);
+  expect(result.results[0]!.ignored).toBeFalsy();
+  expect(result.results[0]!.invalidOptionWarnings).toEqual([]);
+
+  return result.results[0]!.warnings;
+}
+
+function find(warnings: stylelint.Warning[], rule: string): stylelint.Warning | undefined {
+  return warnings.find((warning) => warning.rule === rule);
+}
+
+describe('linting a standalone CSS asset', () => {
+  let cwd: string;
+
+  beforeAll(async () => {
+    cwd = await mkdtemp(join(tmpdir(), 'stylelint-config-theory-'));
+  });
+
+  afterAll(async () => {
+    await rm(cwd, { recursive: true, force: true });
+  });
+
+  it('grades a correctness offense as an error and a convention offense as a warning', async () => {
+    const warnings = await lint(
+      '.td-card {\n  margin: 0px;\n}\n.td-empty {}\n',
+      join(cwd, 'assets/component-td-card.css'),
+      cwd,
+    );
+
+    expect(find(warnings, 'block-no-empty')?.severity).toBe('error');
+    expect(find(warnings, 'length-zero-no-unit')?.severity).toBe('warning');
+  });
+
+  it('reports a CSS syntax error as an error', async () => {
+    const warnings = await lint(
+      '.td-card { color: red;\n',
+      join(cwd, 'assets/component-td-card.css'),
+      cwd,
+    );
+
+    expect(find(warnings, 'CssSyntaxError')?.severity).toBe('error');
+  });
+
+  it('accepts BEM-style class and custom-property names', async () => {
+    const warnings = await lint(
+      '.td-card__title--active {\n  --tdCardGap: 1rem;\n}\n',
+      join(cwd, 'assets/component-td-card.css'),
+      cwd,
+    );
+
+    expect(warnings).toEqual([]);
+  });
+
+  it('cannot be disabled by the theme', async () => {
+    // The whole point of the branch lint is that it is a gate. A theme that
+    // ships its own config, or ignores its own assets, must not silence it.
+    await writeFile(join(cwd, '.stylelintrc.json'), '{"rules":{}}\n');
+    await writeFile(join(cwd, '.stylelintignore'), 'assets/**\n*.liquid\n');
+
+    const warnings = await lint(
+      '.td-empty {}\n',
+      join(cwd, 'assets/component-td-card.css'),
+      cwd,
+    );
+
+    expect(find(warnings, 'block-no-empty')?.severity).toBe('error');
+  });
+});
+
+describe('linting the CSS inside a Liquid stylesheet block', () => {
+  let cwd: string;
+
+  beforeAll(async () => {
+    cwd = await mkdtemp(join(tmpdir(), 'stylelint-config-theory-'));
+  });
+
+  afterAll(async () => {
+    await rm(cwd, { recursive: true, force: true });
+  });
+
+  /** Mask a `.liquid` source and lint it, as the runner does. */
+  async function lintLiquid(lines: string[]): Promise<stylelint.Warning[]> {
+    const masked = maskLiquidStylesheet(lines.join('\n'));
+    expect(masked).not.toBeNull();
+    return lint(masked!, join(cwd, 'sections/td-hero.liquid'), cwd);
+  }
+
+  it('reports an offense at its real line and column in the liquid file', async () => {
+    const lines = [
+      '<div class="td-hero">{{ product.title }}</div>',
+      '{% stylesheet %}',
+      '  .td-hero { color: red; }',
+      '  .td-broken {}',
+      '{% endstylesheet %}',
+      '',
+    ];
+
+    const warnings = await lintLiquid(lines);
+    const offense = find(warnings, 'block-no-empty');
+    const offendingLine = '  .td-broken {}';
+
+    expect(offense?.severity).toBe('error');
+    // Derived, not hard-coded: this is the invariant the mask exists for. The
+    // position must be the one in the `.liquid` file, not in the masked source.
+    expect(offense?.line).toBe(lines.indexOf(offendingLine) + 1);
+    expect(offense?.column).toBe(offendingLine.indexOf('{}') + 1);
+  });
+
+  it('leaves a Liquid-free block clean under the full rule set', async () => {
+    const warnings = await lintLiquid([
+      '{% stylesheet %}',
+      '  .td-hero {',
+      '    margin: var(--td-hero-gap);',
+      "    background: url('hero.png');",
+      '  }',
+      '',
+      '  @media (width >= 40em) {',
+      '    .td-hero { color: red; }',
+      '  }',
+      '{% endstylesheet %}',
+      '',
+    ]);
+
+    expect(warnings).toEqual([]);
+  });
+
+  it('grades a masked interpolation like any other value', async () => {
+    // The value-shape rules used to be disabled inside a block, because a
+    // masked `{{ … }}` stands in as `0`. Liquid here is now an error in its own
+    // right — `StaticStylesheetAndJavascriptTags` reports it — so the substitution
+    // no longer has to read as correct CSS, and the rules stay on. Whichever
+    // rules fire, the author has to remove the Liquid.
+    const warnings = await lintLiquid([
+      '{% stylesheet %}',
+      '  .td-hero {',
+      '    margin: {{ section.settings.gap }}px;',
+      '  }',
+      '{% endstylesheet %}',
+      '',
+    ]);
+
+    expect(warnings.map(({ rule }) => rule)).toContain('declaration-property-value-no-unknown');
+  });
+
+  it('still reports structural offenses inside the block', async () => {
+    const warnings = await lintLiquid([
+      '{% stylesheet %}',
+      '  .td-hero {',
+      '    colr: red;',
+      '    margin: 0px;',
+      '  }',
+      '{% endstylesheet %}',
+      '',
+    ]);
+
+    expect(find(warnings, 'property-no-unknown')?.severity).toBe('error');
+    expect(find(warnings, 'length-zero-no-unit')?.severity).toBe('warning');
+  });
+});