feat(theme-check-vscode): surface orphaned files on startup

[ryandiginomad]

What are you adding in this PR?

Closes #970.

theme-graph already knows which files are orphaned (dead code), and there's a Liquid Theme Check: Find dead code command to list them — but it's easy to miss because you have to know to run it. This surfaces it proactively: on activation, if the theme has orphaned files, the extension shows a single dismissable notification.

• Review → opens the existing dead-code quick pick
• Don't show again → flips the setting off
• Gated by a new themeCheck.checkOrphanedFilesOnBoot setting (default true), mirroring the existing themeCheck.preloadOnBoot pattern

Implementation notes:

• Reuses the whole-theme dead-code detection already exposed via ThemeGraphDeadCodeRequest (ThemeGraphManager.deadCode(rootUri)) — no server changes.
• The startup check finds theme roots via workspace.findFiles('**/.theme-check.yml') (there's no active editor at boot), aggregates orphaned files across roots, and prompts once.
• Refactored makeDeadCode to extract fetchDeadCode + showDeadCodePicker so the command and the startup check share logic — makeDeadCode's behavior is unchanged and covered by a characterization test.
• Wired into both node and browser activation, fire-and-forget so it never blocks or fails activation.

Unit tests: new orphanedFilesOnBoot.spec.ts covers disabled setting / no orphans / orphans → notification / "Don't show again" → setting update / "Review" → picker, plus characterization tests guarding the makeDeadCode refactor. Full theme-check-vscode vitest suite green (23 tests), tsc --noEmit clean, prettier clean.

🤖 AI assistance

Drafted with Claude Code. I reviewed every change, ran the tests, and tophatted the flows below in a real extension host. The orphaned-files detection this builds on is existing Shopify code; this PR adds the startup surfacing plus a shared refactor.

What's next? Any followup issues?

None required. A few knobs I'm happy to adjust in this PR if you have preferences:

• Setting default true (matches the issue's "prompt on start-up" intent) vs opt-in false for less startup noise.
• Changeset marked minor (new feature + setting); can drop to patch given the fixed version group.
• Multi-root: aggregates the count across all theme roots; "Review" opens the first root with orphans. Per-root prompts could be a follow-up if there's appetite.

What did you learn?

• At activation time there's no active editor, so the usual "resolve the theme root from the open document" approach doesn't apply — root discovery uses workspace.findFiles('**/.theme-check.yml') instead.
• Stock Dawn ships 2 orphaned files (assets/component-progress-bar.css, snippets/quick-order-product-row.liquid), so the notification surfaces real signal even on a vanilla theme.

Tophatting

Tested manually against a fresh Dawn clone — which has 2 orphaned files out of the box — plus one intentionally orphaned snippet (3 total), using the web extension host (this also exercises the browser activation path):

cd packages/vscode-extension
pnpm build
git clone --depth 1 https://github.com/Shopify/dawn.git .tmp/dawn
# optional: add an unreferenced snippets/zz-orphan.liquid
pnpm exec vscode-test-web --quality=stable --extensionDevelopmentPath=. .tmp/dawn

1. Boot with orphans → one dismissable notification:

   

2. Review → opens the existing dead-code quick pick with all 3 files:

   

3. Don't show again → writes the setting to user settings:

   

4. Reload with the setting off → no notification on boot.

• I added screenshots of the changes (there's no startup notification before this change, so the screenshots show the new flow)

Before you deploy

• I included a minor bump changeset
• My feature is backward compatible

[ryandiginomad]

Quick check-in — this PR has been ready for review for a week. CLA signed, CI green. Ready whenever the theme-tools team has a window, and happy to address anything that comes up.

[aswamy]

Thanks for the PR @ryandiginomad . Please ensure your PR description follows the PR template here. This ensures that you have run the code and have tested it out manually before submitting.

[aswamy]

Startup check misses supported theme roots. This only scans **/.theme-check.yml, but the existing root detector also supports shopify.extension.toml roots and configless themes inferred from assets + snippets (see find-root.ts (line 7)). Those workspaces can activate the extension but will never get this new orphaned-file prompt.

[ryandiginomad]

Good catch — fixed in 2d33a1f. The startup scan now globs every root signal findRoot recognises ({.theme-check.yml,shopify.extension.toml,snippets/*}) instead of just .theme-check.yml, and each match is resolved to its root via the server's themeGraph/rootUri request, so theme app extensions and configless themes get the prompt too.

[aswamy]

This aggregates total across all config files, but line 42 opens the picker only for firstHit. In a workspace with multiple themes, the notification may say “Found 12 orphaned files” while Review shows only the first theme’s subset.

[aswamy]

In my workspace, i have two separate themes:

[ryandiginomad]

Fixed in 2d33a1f. The check now dedupes the resolved roots and prompts once per theme that has orphaned files, so each notification's count matches the files its own "Review" picker opens — no more cross-theme aggregation. Your two-theme workspace would now get one notification per theme. Added unit tests for the multi-theme and dedupe cases.

[ryandiginomad]

Done — reworked the description to follow the PR template, including a Tophatting section with screenshots: tested in a real extension host against a fresh Dawn clone (boot notification → Review opens the dead-code picker → Don't show again writes the setting → no notification after reload). Happy to adjust anything else.

[aswamy]

@ryandiginomad Please also complete the comments i wrote above

[ryandiginomad]

Thanks for the detailed review and the two-theme screenshot — both inline points are addressed in 2d33a1f (replied in each thread):

1. Missed roots: the startup scan now globs every root signal findRoot recognises ({.theme-check.yml,shopify.extension.toml,snippets/*}), and resolves each match to its root via the server's themeGraph/rootUri request, so theme app extensions and configless themes get the prompt too.

2. Aggregate count vs. first-theme picker: it now dedupes by resolved root and prompts once per theme that has orphaned files, so each notification's count matches the files its own "Review" picker opens — no cross-theme aggregation.

Both behaviors are covered by new unit tests (multi-theme prompting, root dedupe, the wider glob, per-root counts): pnpm vitest run packages/vscode-extension/src/common/orphanedFilesOnBoot.spec.ts → 9 passing. tsc --noEmit and prettier are clean.