fix(plugin): clarify on-demand recovery and preserve package diagnostics

scripts/gen-official-bundle-catalog.spec.ts

@@ -1,6 +1,6 @@
 /** Offline Official catalog ownership, completeness, and freshness checks. */
 
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
@@ -104,4 +104,23 @@ describe('Official bundle catalog generation', () => {
     syncOfficialBundleCatalog(root, false)
     expect(readFileSync(join(root, output), 'utf8')).toContain('Changed')
   })
+
+  it('does not rewrite an already current catalog during explicit generation', () => {
+    const root = fixture()
+    syncOfficialBundleCatalog(root, false)
+    const path = join(root, output)
+    const timestamp = new Date('2000-01-01T00:00:00Z')
+    utimesSync(path, timestamp, timestamp)
+    const before = statSync(path).mtimeMs
+    syncOfficialBundleCatalog(root, false)
+    expect(statSync(path).mtimeMs).toBe(before)
+    expect(() => { syncOfficialBundleCatalog(root, true) }).not.toThrow()
+  })
+
+  it('rejects a missing generated catalog without recreating it during freshness checking', () => {
+    const root = fixture()
+    rmSync(join(root, output))
+    expect(() => { syncOfficialBundleCatalog(root, true) }).toThrow('is stale')
+    expect(existsSync(join(root, output))).toBe(false)
+  })
 })

scripts/gen-official-bundle-catalog.ts

@@ -106,16 +106,19 @@ function localized(value: LocalizedText): string {
 }
 
 /**
- * Write or freshness-check metadata against the owning package resources.
+ * Write changed metadata or freshness-check it against the owning package resources.
  * @param root - Repository root containing source and metadata resources.
  * @param check - Reject drift without changing the generated file.
  */
 export function syncOfficialBundleCatalog(root: string, check: boolean): void {
   const source = renderOfficialBundleCatalog(generateOfficialBundleCatalog(root))
   const path = resolve(root, OUTPUT)
-  if (check) {
-    if (readFileSync(path, 'utf8') !== source) throw new Error(`${OUTPUT} is stale; run pnpm gen-official-bundle-catalog`)
-  } else writeFileSync(path, source)
+  let current: string | undefined
+  try { current = readFileSync(path, 'utf8') }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+  if (current === source) return
+  if (check) throw new Error(`${OUTPUT} is stale; run pnpm gen-official-bundle-catalog`)
+  writeFileSync(path, source)
 }
 
 if (process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {