test(ui-theme): name the dot-directory exclusion and cover a nested manifest

packageFiles() now states the dot-directory exclusion in its JSDoc, and the
inline comment no longer names one concrete temporary-root prefix. The spec
title describes what the case checks, and the case also asserts a manifest one
level below the root so an implementation that only scans the root fails.

packages/client/ui-theme/tests/stylesheet-scan.client.spec.ts

@@ -11,15 +11,22 @@ afterEach(() => {
   for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
 })
 
-it('walks shipped package files and skips dot directories holding transient roots', () => {
+it('skips dot directories holding transient roots', () => {
   const root = mkdtempSync(join(tmpdir(), 'dsh-stylesheet-scan-'))
   roots.push(root)
-  mkdirSync(join(root, 'pkg'))
+  mkdirSync(join(root, 'pkg', 'nested'), { recursive: true })
   writeFileSync(join(root, 'pkg', 'package.json'), '{}')
+  writeFileSync(join(root, 'pkg', 'nested', 'package.json'), '{}')
   mkdirSync(join(root, '.typert-worker-failure-probe'))
   writeFileSync(join(root, '.typert-worker-failure-probe', 'package.json'), '{}')
 
   // The helper reports `/`-separated paths on every platform, so the Windows
-  // temporary root's separators must not reach the expectation.
-  expect(packageFiles(name => name === 'package.json', root)).toEqual([`${root.replaceAll('\\', '/')}/pkg/package.json`])
+  // temporary root's separators must not reach the expectation. Traversal
+  // reports the nested manifest before its parent, and directory order is not
+  // guaranteed, so both sides are compared sorted.
+  const normalized = root.replaceAll('\\', '/')
+  expect(packageFiles(name => name === 'package.json', root).sort()).toEqual([
+    `${normalized}/pkg/nested/package.json`,
+    `${normalized}/pkg/package.json`,
+  ])
 })

packages/client/ui-theme/tests/stylesheet-scan.ts

@@ -73,7 +73,9 @@ export function varReferences(value: string): string[] {
 
 /**
  * Every file shipped as package source whose name the predicate accepts,
- * excluding build output and installed dependencies.
+ * excluding build output, installed dependencies, and dot directories.
+ * Dot directories hold VCS metadata and per-test temporary roots rather than
+ * shipped source, and their owner can remove one while a scan reads it.
  * @param accepts - filename predicate.
  * @param root - tree to walk, the packages directory by default.
  * @returns absolute paths under `root`, `/`-separated on every platform so
@@ -85,8 +87,8 @@ export function packageFiles(accepts: (name: string) => boolean, root: string =
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
       const path = join(dir, entry.name)
       if (entry.isDirectory()) {
-        // Dot directories hold VCS metadata and per-test temporary roots (for
-        // example `.typert-worker-failure-*`), never shipped package source; a
+        // Dot directories hold VCS metadata and the temporary roots each spec
+        // creates inside the package tree, never shipped package source; a
         // concurrent owner can remove one while a scan reads it.
         if (!entry.name.startsWith('.') && entry.name !== 'node_modules' && entry.name !== 'lib' && entry.name !== 'dist') walk(path)
       } else if (accepts(entry.name)) found.push(path.replaceAll('\\', '/'))