td-ai-tools 1.2.11 → 1.3.2

package/skills/shopify-lint/scripts/shopify_lint.py

@@ -16,8 +16,10 @@ SEVERITY_RANK = {"error": 0, "warning": 1, "info": 2}
 
 SKILL_ROOT = Path(__file__).resolve().parents[1]
 ESLINT_RUNNER = SKILL_ROOT / "eslint-plugin-theory" / "bin" / "lint-js.mjs"
+STYLELINT_RUNNER = SKILL_ROOT / "stylelint-config-theory" / "bin" / "lint-css.mjs"
 
 JS_EXTENSIONS = (".js", ".mjs")
+CSS_EXTENSIONS = (".css",)
 LIQUID_EXTENSION = ".liquid"
 
 # Standalone JavaScript is linted only when its filename carries the Theory
@@ -26,15 +28,21 @@ LIQUID_EXTENSION = ".liquid"
 # `{% javascript %}` blocks are always linted regardless of the section name.
 JS_NAME_FILTER = "td-"
 
+# The same policy for CSS: `component-td-card.css` is Theory's, `vendor.css` is
+# not. Stated separately from JS_NAME_FILTER so either can change alone. Liquid
+# `{% stylesheet %}` blocks are always linted regardless of the section name.
+CSS_NAME_FILTER = "td-"
+
 ESLINT_SEVERITY = {2: "error", 1: "warning"}
 
-# Theme Check reports LSP-style zero-indexed positions; ESLint is one-indexed.
-LINE_BASE_OFFSET = 1
+# Stylelint reports a severity string rather than a number, and encodes a CSS
+# syntax error as a rule name rather than a flag.
+STYLELINT_SEVERITIES = ("error", "warning")
+STYLELINT_PARSE_ERROR_RULE = "CssSyntaxError"
 
-LIQUID_PARSE_NOTE = (
-    " (Liquid interpolation is masked before parsing; the reported position "
-    "may be approximate.)"
-)
+# Theme Check reports LSP-style zero-indexed positions; ESLint and Stylelint are
+# both one-indexed.
+LINE_BASE_OFFSET = 1
 
 
 class ShopifyLintError(RuntimeError):
@@ -164,6 +172,22 @@ def run_theme_check(
     return reports
 
 
+def resolve_lint_target(
+    relative: str, repo_root: Path, theme_path: Path
+) -> Path | None:
+    """Absolute path for a changed file, or `None` if it cannot be linted."""
+    absolute = repo_root / relative
+    if not absolute.is_file():
+        # Renamed or deleted after being changed on the branch.
+        return None
+    try:
+        absolute.resolve().relative_to(theme_path.resolve())
+    except ValueError:
+        # Outside the theme root that Theme Check was pointed at.
+        return None
+    return absolute
+
+
 def select_js_targets(
     changed_files: set[str], repo_root: Path, theme_path: Path
 ) -> list[Path]:
@@ -190,16 +214,39 @@ def select_js_targets(
         else:
             continue
 
-        absolute = repo_root / relative
-        if not absolute.is_file():
-            # Renamed or deleted after being changed on the branch.
-            continue
-        try:
-            absolute.resolve().relative_to(theme_path.resolve())
-        except ValueError:
-            # Outside the theme root that Theme Check was pointed at.
+        absolute = resolve_lint_target(relative, repo_root, theme_path)
+        if absolute is not None:
+            targets.append(absolute)
+    return targets
+
+
+def select_css_targets(
+    changed_files: set[str], repo_root: Path, theme_path: Path
+) -> list[Path]:
+    """Pick the modified files worth handing to Stylelint.
+
+    The same policy as `select_js_targets`, one extension along: standalone
+    `.css` is filtered to Theory-owned files by name so vendored stylesheets are
+    left alone, and every modified `.liquid` file is included regardless of its
+    name because the CSS inside a `{% stylesheet %}` block is Theory's either
+    way. The bundled mask returns nothing for a file without such a block, so
+    there is no need to read them here.
+    """
+    targets = []
+    for relative in sorted(changed_files):
+        if relative.endswith(LIQUID_EXTENSION):
+            pass
+        elif relative.endswith(CSS_EXTENSIONS):
+            if relative.endswith(".min.css"):
+                continue
+            if CSS_NAME_FILTER not in PurePosixPath(relative).name.lower():
+                continue
+        else:
             continue
-        targets.append(absolute)
+
+        absolute = resolve_lint_target(relative, repo_root, theme_path)
+        if absolute is not None:
+            targets.append(absolute)
     return targets
 
 
@@ -245,6 +292,97 @@ def run_js_lint(
     return results
 
 
+def run_css_lint(
+    theme_path: Path, targets: list[Path], runner: Path | None = None
+) -> list[dict[str, Any]]:
+    if not targets:
+        return []
+
+    runner_path = runner or STYLELINT_RUNNER
+    if not runner_path.is_file():
+        raise ShopifyLintError(
+            "Theory CSS lint runner is missing; run scripts/setup.sh."
+        )
+
+    payload = json.dumps(
+        {"cwd": str(theme_path), "files": [str(target) for target in targets]}
+    )
+    try:
+        result = subprocess.run(
+            ["node", str(runner_path)],
+            input=payload,
+            cwd=theme_path,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError as error:
+        raise ShopifyLintError("Node.js is not installed or is not on PATH.") from error
+
+    if result.returncode != 0:
+        detail = result.stderr.strip() or result.stdout.strip() or "no output"
+        raise ShopifyLintError(f"Theory CSS lint failed: {detail}")
+
+    try:
+        results = json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        detail = result.stderr.strip() or result.stdout.strip() or "no output"
+        raise ShopifyLintError(f"Theory CSS lint failed: {detail}") from error
+
+    if not isinstance(results, list):
+        raise ShopifyLintError("Theory CSS lint returned an unexpected JSON shape.")
+    return results
+
+
+def stylelint_check_code(warning: dict[str, Any]) -> str:
+    """Namespace a Stylelint rule so its origin is obvious in the report."""
+    rule = warning.get("rule")
+    if not rule:
+        return "stylelint/unknown"
+    if rule == STYLELINT_PARSE_ERROR_RULE:
+        return "stylelint/parse-error"
+    return rule if "/" in rule else f"stylelint/{rule}"
+
+
+def stylelint_severity(warning: dict[str, Any]) -> str:
+    """Map a Stylelint severity.
+
+    A CSS parse error inside a `{% stylesheet %}` block used to be demoted to
+    `info`, on the grounds that masking Liquid out cannot always produce
+    parseable CSS and the author had no reasonable way to fix it. Liquid does
+    not belong in the block in the first place — Theme Check's
+    `StaticStylesheetAndJavascriptTags` reports it as an error — so the fix is
+    well defined and a parse error is graded like any other.
+    """
+    severity = str(warning.get("severity", ""))
+    return severity if severity in STYLELINT_SEVERITIES else "warning"
+
+
+def normalize_stylelint_results(results: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Convert the CSS runner's results into the report shape Theme Check emits."""
+    reports = []
+    for result in results:
+        warnings = result.get("warnings") or []
+        if not warnings:
+            continue
+        path = str(result.get("path", ""))
+        offenses = []
+        for warning in warnings:
+            offenses.append(
+                {
+                    "check": stylelint_check_code(warning),
+                    "severity": stylelint_severity(warning),
+                    "message": str(warning.get("text", "")),
+                    "start_row": max(int(warning.get("line", 1)) - LINE_BASE_OFFSET, 0),
+                    "start_column": max(
+                        int(warning.get("column", 1)) - LINE_BASE_OFFSET, 0
+                    ),
+                }
+            )
+        reports.append({"path": path, "offenses": offenses})
+    return reports
+
+
 def eslint_check_code(message: dict[str, Any]) -> str:
     """Namespace an ESLint rule so its origin is obvious in the report."""
     rule = message.get("ruleId")
@@ -253,16 +391,17 @@ def eslint_check_code(message: dict[str, Any]) -> str:
     return rule if "/" in rule else f"eslint/{rule}"
 
 
-def eslint_severity(message: dict[str, Any], path: str) -> str:
-    """Map an ESLint severity, demoting parse errors inside Liquid.
+def eslint_severity(message: dict[str, Any]) -> str:
+    """Map an ESLint severity.
 
-    Masking Liquid out of a `{% javascript %}` block cannot always produce
-    valid JavaScript — control flow that straddles a syntax boundary defeats
-    it. Reporting those at `info` keeps them visible without ever failing a run
-    that the author has no reasonable way to fix.
+    A parse error inside a `{% javascript %}` block used to be demoted to
+    `info`, because Liquid control flow that straddles a JavaScript syntax
+    boundary cannot be masked into parseable code and the author had no
+    reasonable way to fix it. That Liquid is now an offense of its own —
+    Theme Check's `StaticStylesheetAndJavascriptTags` reports it as an error — so
+    a parse error is graded like any other: either the block still holds Liquid,
+    which has to go, or the JavaScript itself is broken.
     """
-    if message.get("fatal") and path.endswith(LIQUID_EXTENSION):
-        return "info"
     return ESLINT_SEVERITY.get(message.get("severity"), "warning")
 
 
@@ -276,15 +415,11 @@ def normalize_eslint_results(results: list[dict[str, Any]]) -> list[dict[str, An
         path = str(result.get("filePath", ""))
         offenses = []
         for message in messages:
-            severity = eslint_severity(message, path)
-            text = str(message.get("message", ""))
-            if severity == "info" and message.get("fatal"):
-                text += LIQUID_PARSE_NOTE
             offenses.append(
                 {
                     "check": eslint_check_code(message),
-                    "severity": severity,
-                    "message": text,
+                    "severity": eslint_severity(message),
+                    "message": str(message.get("message", "")),
                     "start_row": max(int(message.get("line", 1)) - LINE_BASE_OFFSET, 0),
                     "start_column": max(
                         int(message.get("column", 1)) - LINE_BASE_OFFSET, 0
@@ -422,6 +557,12 @@ def build_parser() -> argparse.ArgumentParser:
         default=bool(os.environ.get("SHOPIFY_LINT_SKIP_JS")),
         help="Skip JavaScript linting and report Theme Check offenses only.",
     )
+    parser.add_argument(
+        "--skip-css",
+        action="store_true",
+        default=bool(os.environ.get("SHOPIFY_LINT_SKIP_CSS")),
+        help="Skip CSS linting and report the other linters' offenses only.",
+    )
     return parser
 
 
@@ -439,7 +580,15 @@ def main() -> int:
         if not arguments.skip_js:
             targets = select_js_targets(changed_files, repo_root, theme_path)
             js_reports = normalize_eslint_results(run_js_lint(theme_path, targets))
-        reports = merge_reports(theme_reports, js_reports, repo_root=repo_root)
+        css_reports: list[dict[str, Any]] = []
+        if not arguments.skip_css:
+            css_targets = select_css_targets(changed_files, repo_root, theme_path)
+            css_reports = normalize_stylelint_results(
+                run_css_lint(theme_path, css_targets)
+            )
+        reports = merge_reports(
+            theme_reports, js_reports, css_reports, repo_root=repo_root
+        )
         filtered = filter_reports(reports, changed_files, repo_root)
     except ShopifyLintError as error:
         print(f"shopify-lint: {error}", file=sys.stderr)

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

@@ -0,0 +1,9 @@
+# Intentionally empty.
+#
+# bin/lint-css.mjs passes this file as Stylelint's `ignorePath`. Naming any
+# path there replaces Stylelint's default lookup for a `.stylelintignore` in
+# the working directory, which is the point: the branch lint is a gate, so a
+# theme must not be able to silence it by adding an ignore file of its own.
+#
+# Do not add patterns here. Scoping is decided by scripts/shopify_lint.py,
+# which passes the runner an explicit list of branch-modified files.

package/skills/shopify-lint/stylelint-config-theory/README.md

@@ -0,0 +1,144 @@
+# stylelint-config-theory
+
+Theory Digital's Stylelint configuration for Shopify theme CSS, plus a mask that
+lints the CSS inside Liquid `{% stylesheet %}` 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` and
+`eslint-plugin-theory`, it ships as TypeScript source: `npm install && npm run
+build` produces the `dist/` that `bin/lint-css.mjs` imports.
+
+## Rules
+
+No custom rules yet — the configuration is the upstream
+`stylelint-config-standard` set, regraded. The two shared configs it is built
+from split along the line this skill already draws for JavaScript:
+
+| Layer | Default | What it covers |
+| --- | --- | --- |
+| `stylelint-config-recommended` | **error** | Unknown properties, at-rules, and pseudo-selectors; duplicate declarations and selectors; invalid values, hex colours, and media queries; empty blocks |
+| `stylelint-config-standard` additions | warning | Notational conventions — `color-function-notation`, `alpha-value-notation`, `length-zero-no-unit`, `shorthand-property-no-redundant-values`, `import-notation`, `value-keyword-case`, the `*-empty-line-before` family |
+
+Errors fail the branch lint at its default `--fail-level error`; warnings are
+reported but advisory, matching how the bundled Theme Check rules behave. The
+Stop hooks run at `--fail-level warning`, so warnings block handoff too.
+
+The split is derived from `Object.keys(recommended.rules)` at build time rather
+than listed by hand, so a rule promoted into the recommended config becomes an
+error on the next dependency bump with no edit here.
+
+Note that Stylelint removed its ~76 purely stylistic rules in v15 and v16, so
+this configuration does not check indentation, quote style, brace placement, or
+hex casing. Formatting is not Stylelint's job any more.
+
+### Opt-in rules
+
+Shipped disabled, each because it needs a decision that has not been made yet:
+
+| Rule | Why it is off |
+| --- | --- |
+| `selector-class-pattern` | Standard's default pattern is kebab-case only and 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-id-pattern` | Same pattern, same reason. |
+| `custom-property-pattern` | Same pattern, applied to `--custom-properties`. |
+| `keyframes-name-pattern` | Same pattern, applied to `@keyframes` names. |
+
+`no-descending-specificity` is enabled but demoted to a warning. It lives in the
+recommended config, so it would otherwise be an error, and it is too noisy on
+real theme CSS to block a handoff over.
+
+## Liquid handling
+
+`{% stylesheet %}` blocks are linted in every modified `.liquid` file regardless
+of the file's name, because that CSS is Theory's either way.
+
+Stylelint has no preprocessing hook — its `processors` option is experimental and
+only exposes `postprocess` — so extraction happens in `bin/lint-css.mjs`, which
+masks the file and hands the result to `stylelint.lint()` as `code` with the real
+`.liquid` path as `codeFilename`.
+
+`maskLiquidStylesheet` is **length-preserving**: it blanks the whole file to
+spaces, keeping newlines at their original indices, then copies back only the
+`{% stylesheet %}` bodies and blanks the Liquid constructs inside them. Every
+line and column reported against the masked source is therefore already correct
+for the original file, with no offset arithmetic anywhere. It is the CSS twin of
+`eslint-plugin-theory/src/liquid/mask.ts`, kept as a separate file so the two
+bundled packages stay independently installable.
+
+A file is skipped entirely — the mask returns `null` — when it has no complete
+`{% stylesheet %}` … `{% endstylesheet %}` pair, when every block sits inside a
+`{% comment %}` or `{% raw %}` region, when every block carries an argument
+(`{% stylesheet 'scss' %}`, the pre-2020 Sass form still found in older themes),
+or when every body is blank once masked. So callers can pass every modified
+`.liquid` file without reading it first.
+
+### Liquid in a block is an offense, not a case to accommodate
+
+Shopify does not render Liquid inside a `{% stylesheet %}` tag: the block's
+contents are concatenated into the theme's compiled CSS verbatim, so
+interpolation found there is already broken theme code. Theme Check's
+`StaticStylesheetAndJavascriptTags` reports it as an **error**, at its exact
+position in the `.liquid` file — see `theme-check-theory/README.md`.
+
+That is why this package no longer bends its rules around masked Liquid. A
+Liquid output tag inside a block is still replaced by `0` padded with blanks —
+without a stand-in value the block would collapse into a parse error, hiding
+every real offense after it — but the rules that inspect the shape of a value or
+an at-rule prelude stay on. `margin: {{ s.gap }}px` masks to `margin: 0    px`
+and is reported as an unknown value; the fix is the same fix the Liquid offense
+asks for. There is one config, and a `{% stylesheet %}` block is graded exactly
+as a standalone `.css` file is.
+
+For the same reason a CSS syntax error inside `.liquid` is a plain error. It used
+to be demoted to `info` — masking cannot always yield parseable CSS, and the
+author had no defined fix — but removing the Liquid is now that fix.
+
+`{% comment %}` and `{% raw %}` bodies *inside* a block are still blanked before
+the CSS is parsed, so their contents are never mistaken for CSS. The tags
+themselves are reported by the Theme Check check: Liquid comments are not
+comments here either.
+
+## The lint is a gate
+
+No Stylelint configuration is written to the project root and the theme's own
+configuration is never consulted. `bin/lint-css.mjs` passes an inline `config`
+object, which stops Stylelint searching for a `.stylelintrc`, and names this
+package's comment-only `.stylelintignore` as `ignorePath`, which replaces
+Stylelint's default lookup for a `.stylelintignore` in the working directory.
+Without that second step a theme could silence the lint with an ignore file, and
+Stylelint reports an ignored file as no result at all rather than as a marker —
+so the runner also asserts it got exactly one result per file.
+
+Override the rules per project with `SHOPIFY_LINT_STYLELINT_CONFIG=<path>`
+pointing at a module that exports a `createConfig` function.
+
+## Development
+
+```bash
+npm install
+npm run build     # tsc -p tsconfig.build.json -> dist/
+npm test          # vitest run
+npm run test:watch
+```
+
+`src/build.test.ts` typechecks under the build config, because
+`scripts/setup.sh` runs `npm run build` and a type error there breaks setup for
+every consumer of the skill.
+
+## Adding a rule
+
+The package has no `src/rules/` directory yet. To add the first custom rule:
+
+1. Create `src/rules/<name>.ts` as a Stylelint plugin rule
+   (`stylelint.createPlugin('theory/<name>', …)`).
+2. Register it in a `plugin` export in `src/index.ts`, and add `plugins` to the
+   object `createConfig` returns in `src/config.ts`.
+3. Add `src/rules/<name>.test.ts` linting real CSS through `stylelint.lint()`.
+4. Give it a severity in `src/config.ts` — decide explicitly whether it is a
+   correctness rule (error) or a convention (warning). There is no Liquid
+   variant to configure: masked Liquid only appears in a block that is already
+   failing the lint.
+5. Document it in the table above.
+
+Nothing outside this package needs changing: `bin/lint-css.mjs` reads whatever
+`createConfig` returns, and `scripts/shopify_lint.py` already passes a
+`theory/`-namespaced rule through as its own check code.

package/skills/shopify-lint/stylelint-config-theory/bin/lint-css.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * CSS lint runner spawned by scripts/shopify_lint.py.
+ *
+ * Reads `{"cwd": "<theme root>", "files": ["<absolute path>", ...]}` on stdin
+ * and writes an array of per-file results to stdout:
+ *
+ *   [{ "path", "warnings": [{ line, column, rule, severity, text }] }, ...]
+ *
+ * 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.
+ *
+ * Unlike the JavaScript runner, this one does not emit Stylelint's native
+ * results. Two reasons, both load-bearing:
+ *
+ *   1. A `LintResult` carries an internal `_postcssResult`, which is a circular
+ *      structure — `JSON.stringify` on it throws.
+ *   2. A `parseErrors` entry serialises its PostCSS node, and that embeds the
+ *      entire source text of the file in the payload.
+ *
+ * So each result is projected down to the fields the Python side reads, with
+ * `parseErrors` folded into `warnings` (Stylelint's own formatters do the same;
+ * its `json` formatter does not, which is why a caller reading only `warnings`
+ * would silently drop them).
+ */
+
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * Naming any path as Stylelint's `ignorePath` replaces its default lookup for a
+ * `.stylelintignore` in the working directory. That is deliberate: the branch
+ * lint is a gate, so a theme must not be able to silence it with an ignore
+ * file. The file this points at is committed and contains only comments.
+ */
+const IGNORE_PATH = join(PACKAGE_ROOT, '.stylelintignore');
+
+const LIQUID_EXTENSION = '.liquid';
+
+function fail(message) {
+  process.stderr.write(`theory css 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');
+}
+
+async function loadConfig(createConfig) {
+  const override = process.env.SHOPIFY_LINT_STYLELINT_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;
+}
+
+/**
+ * Reduce one Stylelint result to the shape the Python side consumes.
+ *
+ * `parseErrors` are PostCSS warnings and carry no `rule`, so they are labelled
+ * `CssSyntaxError` to join the syntax errors Stylelint already reports that way.
+ */
+function project(path, result) {
+  const warnings = (result.warnings ?? []).map((warning) => ({
+    line: warning.line,
+    column: warning.column,
+    rule: warning.rule,
+    severity: warning.severity,
+    text: warning.text,
+  }));
+
+  for (const parseError of result.parseErrors ?? []) {
+    warnings.push({
+      line: parseError.line,
+      column: parseError.column,
+      rule: 'CssSyntaxError',
+      severity: 'error',
+      text: parseError.text,
+    });
+  }
+
+  return { path, warnings };
+}
+
+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 stylelint;
+  let createConfig;
+  let maskLiquidStylesheet;
+  try {
+    stylelint = (await import('stylelint')).default;
+    ({ createConfig } = await import('../dist/config.js'));
+    ({ maskLiquidStylesheet } = await import('../dist/index.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();
+  // One config for both sources: a `{% stylesheet %}` block is graded exactly as
+  // a standalone `.css` file is.
+  const config = buildConfig();
+
+  const results = [];
+  for (const file of files) {
+    const isLiquid = file.toLowerCase().endsWith(LIQUID_EXTENSION);
+
+    let code;
+    try {
+      code = await readFile(file, 'utf8');
+    } catch {
+      // Deleted between Git listing it and us reading it; the branch runner
+      // already tolerates that for the other linters.
+      continue;
+    }
+
+    if (isLiquid) {
+      code = maskLiquidStylesheet(code);
+      // No `{% stylesheet %}` block worth linting, so the file is not CSS at
+      // all — callers can pass every modified `.liquid` file blindly.
+      if (code === null) {
+        continue;
+      }
+    }
+
+    let linted;
+    try {
+      linted = await stylelint.lint({
+        code,
+        codeFilename: file,
+        config,
+        cwd,
+        // Stylelint applies its ignore rules to `codeFilename` too, and returns
+        // an empty result set rather than a marker when one matches. Both of
+        // these are needed to keep that from silencing the gate; the assertion
+        // below catches anything they miss.
+        ignorePath: IGNORE_PATH,
+        disableDefaultIgnores: true,
+        quietDeprecationWarnings: true,
+      });
+    } catch (error) {
+      // `lint()` resolves for CSS syntax errors and rejects only when it could
+      // not run at all — a broken config, an unresolvable dependency.
+      fail(`could not lint ${file}: ${error.message}`);
+    }
+
+    if (linted.results.length !== 1) {
+      fail(
+        `expected one result for ${file}, got ${linted.results.length}. ` +
+          'Stylelint ignored the file, which would report it as clean.',
+      );
+    }
+
+    const [result] = linted.results;
+    if (result.ignored) {
+      fail(`${file} was ignored by Stylelint, which would report it as clean.`);
+    }
+    if (result.invalidOptionWarnings?.length) {
+      // The bundled config is broken. That is a setup error, not a finding
+      // about the theme, so it must not be reported as a lint offense.
+      fail(
+        'the bundled Stylelint configuration is invalid: ' +
+          result.invalidOptionWarnings.map((warning) => warning.text).join('; '),
+      );
+    }
+
+    results.push(project(file, result));
+  }
+
+  process.stdout.write(JSON.stringify(results));
+}
+
+main().catch((error) => {
+  fail(error?.stack ?? String(error));
+});