perf: speed up ValidScopedCSSClass in the language server

Two changes that together drop the LSP save latency introduced by
ValidScopedCSSClass from ~4.5s to <500ms on large themes after the
first save of a session.

1. Session-scoped CSS class cache in runChecks

Before, every save tore down the getCSSClassesForURI memoization and
re-parsed every .liquid file with a {% stylesheet %} tag to rebuild
the theme-wide class set. Now the Map<uri, Promise<Set<string>>>
lives at makeRunChecks scope. When a save fires, the saved URI is
evicted from the cache; every other entry stays warm. First save
pays the full scan; subsequent saves re-parse one file.

2. Substring short-circuit in extractCSSClassesFromLiquidUri

Skip toLiquidHtmlAST entirely when source contains no
'{% stylesheet'. On Horizon (240 liquid files, 128 with stylesheet
tags) this skips ~47% of parses on the first scan. Also helps the
CLI: ~19.2s → ~17.4s on Horizon.

Also adds [theme-check] timing logs in runChecks for profiling.

Author: aswamy

.changeset/perf-valid-scoped-css-class-session-cache.md

@@ -0,0 +1,6 @@
+---
+'@shopify/theme-check-common': patch
+'@shopify/theme-language-server-common': patch
+---
+
+Reduce `ValidScopedCSSClass` save latency on large themes. Parsing of theme-wide stylesheets is now reused across saves within a language-server session and only invalidated for the file the user just edited. Also skips full syntax-tree parsing of Liquid files that contain no stylesheet tag at all. Fixes the save-lag reported in [#1179](https://github.com/Shopify/theme-tools/issues/1179).

packages/theme-check-common/src/utils/styles.ts

@@ -41,6 +41,11 @@ export async function extractCSSClassesFromLiquidUri(
   const classes = new Set<string>();
   try {
     const source = await fs.readFile(uri);
+    // Most liquid files have no {% stylesheet %} tag — skip the AST parse
+    // entirely when the tag isn't present. Saves ~20ms/file on large themes.
+    if (!/\{%-?\s+stylesheet/.test(source)) {
+      return classes;
+    }
     const ast = toLiquidHtmlAST(source);
     if (ast instanceof Error) return classes;
     const cssStrings = visit<SourceCodeType.LiquidHtml, string>(ast, {

packages/theme-language-server-common/src/diagnostics/runChecks.ts

@@ -36,6 +36,12 @@ export function makeRunChecks(
     'fs' | 'loadConfig' | 'themeDocset' | 'jsonValidationSet' | 'getMetafieldDefinitions'
   > & { cssLanguageService?: CSSLanguageService; themeGraphManager?: ThemeGraphManager },
 ) {
+  // Session-scoped cache of CSS classes per file URI. Living at the
+  // makeRunChecks scope means each save only re-parses files that actually
+  // changed — ValidScopedCSSClass's per-save full-theme scan drops from
+  // O(files-with-stylesheet) parses to O(1) re-parse of the saved file.
+  const cssClassCache = new Map<string, Promise<Set<string>>>();
+
   return async function runChecks(triggerURIs: string[]): Promise<void> {
     // This function takes an array of triggerURIs so that we can correctly
     // recheck on file renames that came from out of bounds in a
@@ -46,23 +52,41 @@ export function makeRunChecks(
     //  theme1/snippets/b.liquid
     //
     // then we recheck theme1
+    const runStart = Date.now();
+    console.error(
+      `[theme-check] runChecks start — ${triggerURIs.length} trigger URI(s): ${triggerURIs
+        .map((u) => u.split('/').pop())
+        .join(', ')}`,
+    );
+    // Evict changed files from the session cache before running.
+    for (const uri of triggerURIs) cssClassCache.delete(uri);
     const fileExists = makeFileExists(fs);
     const rootURIs = await Promise.all(triggerURIs.map((uri) => findRoot(uri, fileExists)));
     const deduplicatedRootURIs = new Set<string>(rootURIs.filter((x): x is string => !!x));
     await Promise.all([...deduplicatedRootURIs].map(runChecksForRoot));
+    console.error(`[theme-check] runChecks done in ${Date.now() - runStart}ms`);
 
     return;
 
     async function runChecksForRoot(configFileRootUri: string) {
+      const rootStart = Date.now();
       const config = await loadConfig(configFileRootUri, fs);
       const theme = documentManager.theme(config.rootUri);
+      console.error(
+        `[theme-check]   root ${config.rootUri.split('/').slice(-2).join('/')} — ${
+          theme.length
+        } file(s)`,
+      );
 
+      const cssStart = Date.now();
       const cssOffenses = cssLanguageService
         ? await Promise.all(
             theme.map((sourceCode) => getCSSDiagnostics(cssLanguageService, sourceCode)),
           ).then((offenses) => offenses.flat())
         : [];
+      console.error(`[theme-check]   cssDiagnostics: ${Date.now() - cssStart}ms`);
 
+      const checkStart = Date.now();
       const themeOffenses = await check(theme, config, {
         fs,
         themeDocset,
@@ -79,11 +103,14 @@ export function makeRunChecks(
           return themeGraphManager.getDependencies(uri);
         },
 
-        async getCSSClassesForURI(uri: string): Promise<Set<string>> {
-          if (uri.endsWith('.css')) {
-            return extractCSSClassesFromAssetUri(uri, fs);
-          }
-          return extractCSSClassesFromLiquidUri(uri, fs);
+        getCSSClassesForURI(uri: string): Promise<Set<string>> {
+          const cached = cssClassCache.get(uri);
+          if (cached) return cached;
+          const promise = uri.endsWith('.css')
+            ? extractCSSClassesFromAssetUri(uri, fs)
+            : extractCSSClassesFromLiquidUri(uri, fs);
+          cssClassCache.set(uri, promise);
+          return promise;
         },
 
         // TODO should do something for app blocks?
@@ -112,6 +139,11 @@ export function makeRunChecks(
           return doc.getLiquidDoc();
         },
       });
+      console.error(
+        `[theme-check]   check() (all rules): ${Date.now() - checkStart}ms — ${
+          themeOffenses.length
+        } offense(s)`,
+      );
       const offenses = [...themeOffenses, ...cssOffenses];
 
       // We iterate over the theme files (as opposed to offenses) because if
@@ -121,6 +153,7 @@ export function makeRunChecks(
         const sourceCodeOffenses = offenses.filter((offense) => offense.uri === sourceCode.uri);
         diagnosticsManager.set(sourceCode.uri, sourceCode.version, sourceCodeOffenses);
       }
+      console.error(`[theme-check]   root done in ${Date.now() - rootStart}ms`);
     }
   };
 }