@gscdump/nuxt 0.19.0

package/app/composables/useGscAnalyzer.ts

@@ -0,0 +1,374 @@
+// Per-site analyzer. Two modes, picked from `/source-info`:
+//
+//  - `browser-attached` — server source is SQL-capable and advertises
+//    `attachedTables`; we boot DuckDB-WASM in the browser and attach parquets
+//    for local querying. Fastest path for large dashboards.
+//  - `server` — everything else (GSC API live row source, engine sources
+//    without attach support, etc.). `analyze()` proxies to the server POST
+//    endpoint; `query()` throws since there's no local SQL engine.
+//
+// Cached per-site so navigation between panels on the same site doesn't
+// re-boot. Writes progress to the shared map so <GscBootProgress> lights up
+// on boot regardless of mode.
+
+import type { AnalysisParams, AnalysisResult } from '@gscdump/analysis'
+import type { AnalysisSourcesResponse, SourceInfoResponse } from '@gscdump/contracts'
+import type { AttachedTablesHandle, BrowserAnalysisRuntime, DuckDBWasmBootResult, QueryResult } from '@gscdump/engine-duckdb-wasm'
+import type { SiteLoadProgress } from './useGscAnalytics'
+import { defaultAnalyzerRegistry } from '@gscdump/analysis'
+import { coerceRow } from '@gscdump/engine'
+import { useGscSharedSiteResource } from './_useGscSharedSiteResource'
+import { useGscAnalyticsContext } from './useGscAnalytics'
+import { useGscAnalyticsClient } from './useGscAnalyticsClient'
+import { useGscAnalyticsConfig } from './useGscAnalyticsConfig'
+import { loadSourceInfoFor } from './useGscAnalyticsSourceInfo'
+import { resolveGscAuthHeaders } from './useGscAuth'
+
+export interface GscAnalyzerTimings {
+  bootMs: number
+  manifestMs: number
+  attachMs: number
+}
+
+export interface GscAnalyzerInstance {
+  ready: Ref<boolean>
+  initializing: Ref<boolean>
+  error: Ref<Error | null>
+  attachedTables: Ref<string[]>
+  timings: Ref<GscAnalyzerTimings | null>
+  /** Server-reported manifest version of the currently-attached snapshot. */
+  manifestVersion: Ref<string | undefined>
+  query: (sql: string, params?: unknown[]) => Promise<QueryResult>
+  analyze: (params: AnalysisParams, opts?: { signal?: AbortSignal }) => Promise<AnalysisResult & { queryMs: number }>
+  /**
+   * Re-probe `analysis-sources`; if the manifest version changed since the
+   * last attach, detach views and re-attach against the fresher parquet
+   * partitions in place. No-op for `server`-mode analyzers and when the
+   * version matches. Resolves to true if the runtime re-attached.
+   */
+  refresh: () => Promise<boolean>
+  dispose: () => Promise<void>
+}
+
+const EMPTY_TABLES: readonly string[] = Object.freeze([])
+
+/**
+ * Get (or create) an analyzer for a site. Per-site cached across the app so
+ * pages sharing a site reuse the boot. Refcounted — auto-disposes when the
+ * last consumer unmounts. The returned refs are `computed` over the currently
+ * bound cached instance; switching `siteId` rebinds and the computeds track
+ * the new instance with no manual mirroring.
+ */
+export function useGscAnalyzer(siteId: MaybeRefOrGetter<string | null | undefined>): GscAnalyzerInstance & { currentSiteId: Ref<string | null> } {
+  const ctx = useGscAnalyticsContext()
+  const { bound, currentSiteId } = useGscSharedSiteResource<GscAnalyzerInstance>('analyzer', siteId, {
+    factory: id => createInstance(id, ctx.patchProgress, () => loadSourceInfoFor(id) as Promise<SourceInfoResponse>),
+    onDispose: inst => inst.dispose(),
+  })
+
+  // Computed views over the bound instance. Reactive on both site switch
+  // (bound changes) and inner ref updates on the cached instance.
+  const ready = computed(() => bound.value?.ready.value ?? false) as unknown as Ref<boolean>
+  const initializing = computed(() => bound.value?.initializing.value ?? false) as unknown as Ref<boolean>
+  const error = computed(() => bound.value?.error.value ?? null) as unknown as Ref<Error | null>
+  const attachedTables = computed(() => bound.value?.attachedTables.value ?? (EMPTY_TABLES as string[])) as unknown as Ref<string[]>
+  const timings = computed(() => bound.value?.timings.value ?? null) as unknown as Ref<GscAnalyzerTimings | null>
+  const manifestVersion = computed(() => bound.value?.manifestVersion.value) as unknown as Ref<string | undefined>
+
+  async function query(sql: string, params?: unknown[]): Promise<QueryResult> {
+    const inst = bound.value
+    if (!inst)
+      throw new Error('useGscAnalyzer: no site bound')
+    return inst.query(sql, params)
+  }
+
+  async function analyze(params: AnalysisParams, opts?: { signal?: AbortSignal }): Promise<AnalysisResult & { queryMs: number }> {
+    const inst = bound.value
+    if (!inst)
+      throw new Error('useGscAnalyzer: no site bound')
+    return inst.analyze(params, opts)
+  }
+
+  async function refresh(): Promise<boolean> {
+    const inst = bound.value
+    if (!inst)
+      return false
+    return inst.refresh()
+  }
+
+  return {
+    ready,
+    initializing,
+    error,
+    attachedTables,
+    timings,
+    manifestVersion,
+    refresh,
+    currentSiteId,
+    query,
+    analyze,
+    // No-op: lifecycle is owned by the shared bag's onScopeDispose hook.
+    // Kept for API compat with consumers that opportunistically call dispose().
+    dispose: async (): Promise<void> => {},
+  }
+}
+
+function createInstance(
+  siteId: string,
+  patchProgress: (id: string, p: Partial<SiteLoadProgress>) => void,
+  sourceInfoLoader: () => Promise<SourceInfoResponse>,
+): GscAnalyzerInstance {
+  const ready = ref(false)
+  const initializing = ref(true)
+  const error = ref<Error | null>(null)
+  const attachedTables = ref<string[]>([])
+  const timings = ref<GscAnalyzerTimings | null>(null)
+  const manifestVersion = ref<string | undefined>(undefined)
+
+  function patch(p: Partial<SiteLoadProgress>): void {
+    patchProgress(siteId, { source: 'duckdb', ...p })
+  }
+
+  let runtime: BrowserAnalysisRuntime | null = null
+  let bootedDb: DuckDBWasmBootResult | null = null
+  let attachedHandle: AttachedTablesHandle | null = null
+  let mode: 'browser-attached' | 'server' = 'server'
+  const inFlight = new Map<string, Promise<AnalysisResult & { queryMs: number }>>()
+
+  // Cross-origin: if the host returns relative parquet URLs (`/api/r2-data/…`)
+  // and `apiBase` is set, prefix them so DuckDB-WASM hits the data origin
+  // rather than the consumer's own host. Same-origin / absolute URLs pass
+  // through unchanged.
+  function rewriteParquetUrl(url: string): string {
+    const apiBase = useGscAnalyticsConfig().apiBase
+    if (!apiBase || !url.startsWith('/'))
+      return url
+    return `${apiBase.replace(/\/+$/, '')}${url}`
+  }
+
+  async function attachFromSources(sources: AnalysisSourcesResponse): Promise<{ attached: number, total: number }> {
+    if (!bootedDb)
+      throw new Error('useGscAnalyzer: attachFromSources called before DuckDB boot')
+
+    const tables = Object.entries(sources.tables)
+      .filter(([, urls]) => Array.isArray(urls) && urls.length > 0)
+      .map(([table, urls]) => ({ table, urls: urls.map(rewriteParquetUrl) }))
+
+    const total = tables.reduce((n, t) => n + t.urls.length, 0)
+    patch({ stage: 'attach', filesTotal: total, filesAttached: 0 })
+
+    // Cross-origin parquet GETs need the host-supplied auth header (same one
+    // useGscFetch attaches to /api/__gsc/* calls). DuckDB-WASM runs raw fetch
+    // under the hood, so we pass the header through fetchInit. Cookies aren't
+    // useful here — the parquet origin (gscdump.com) and the host page sit in
+    // different session realms when the consumer mode is active.
+    const extraHeaders = resolveGscAuthHeaders()
+    const hasExtra = Object.keys(extraHeaders).length > 0
+    let attached = 0
+    const { attachParquetUrlTables } = await import('@gscdump/engine-duckdb-wasm')
+    const handle = await attachParquetUrlTables({
+      db: bootedDb.db,
+      conn: bootedDb.conn,
+      tables,
+      version: sources.manifestVersion,
+      fetchInit: hasExtra
+        ? { credentials: 'omit', headers: extraHeaders }
+        : { credentials: 'same-origin' },
+      onFileAttached: () => {
+        attached++
+        patch({ filesAttached: attached })
+      },
+    })
+    attachedHandle = handle
+    // `handle.tables` reflects what *actually* attached — `attachParquetUrlTables`
+    // drops tables on fetch failure, so the requested list can over-report.
+    // Use the authoritative list so downstream pre-checks (e.g. the engine's
+    // AttachedTableMissingError fast-fail) get an accurate view.
+    attachedTables.value = handle.tables
+    manifestVersion.value = sources.manifestVersion
+    return { attached, total }
+  }
+
+  const boot = (async () => {
+    patch({ stage: 'manifest', startedAt: Date.now(), filesAttached: 0, filesTotal: 0, error: undefined, endedAt: undefined })
+    // Probe the server-resolved source first. Its kind + attachedTables bit
+    // decides whether we boot DuckDB-WASM (expensive) or proxy to the server.
+    const info = await sourceInfoLoader()
+    mode = info.browserAttachEligible ? 'browser-attached' : 'server'
+
+    if (mode === 'server') {
+      // No local runtime; analyze() posts to the server. Mark ready so the
+      // shared progress UI stops spinning.
+      timings.value = { bootMs: 0, manifestMs: 0, attachMs: 0 }
+      ready.value = true
+      patch({ stage: 'ready', endedAt: Date.now() })
+      return null
+    }
+
+    const cfg = useGscAnalyticsConfig().duckdbBundleBase
+    patch({ stage: 'wasm' })
+    const t0 = performance.now()
+    // Dynamic import so server/consumer-mode hosts (no browser SQL) never pull
+    // the wasm engine into their client bundle. The static type-only import at
+    // top of the file keeps the type signatures available without an emit.
+    const { bootDuckDBWasm, createBrowserAnalysisRuntime } = await import('@gscdump/engine-duckdb-wasm')
+    bootedDb = await bootDuckDBWasm(cfg
+      ? {
+          bundles: {
+            mvp: { mainModule: `${cfg}/duckdb-mvp.wasm`, mainWorker: `${cfg}/duckdb-browser-mvp.worker.js` },
+            eh: { mainModule: `${cfg}/duckdb-eh.wasm`, mainWorker: `${cfg}/duckdb-browser-eh.worker.js` },
+          },
+        }
+      : undefined)
+    const bootMs = performance.now() - t0
+
+    patch({ stage: 'manifest' })
+    const t1 = performance.now()
+    const sources = await useGscAnalyticsClient().getAnalysisSources(siteId) as AnalysisSourcesResponse
+    const manifestMs = performance.now() - t1
+
+    const t2 = performance.now()
+    const { total } = await attachFromSources(sources)
+    const attachMs = performance.now() - t2
+
+    runtime = createBrowserAnalysisRuntime(bootedDb, { schema: 'main', attachedTables: attachedTables.value })
+    runtime.setVersion(sources.manifestVersion)
+    timings.value = { bootMs, manifestMs, attachMs }
+    ready.value = true
+    patch({ stage: 'ready', filesAttached: total, endedAt: Date.now() })
+    return runtime
+  })()
+    .catch((e) => {
+      const err = e instanceof Error ? e : new Error(String(e))
+      error.value = err
+      patch({ stage: 'error', error: err.message, endedAt: Date.now() })
+      throw err
+    })
+    .finally(() => {
+      initializing.value = false
+    })
+
+  // Don't let the boot promise crash the runtime — error.value surfaces it.
+  boot.catch(() => {})
+
+  async function query(sql: string, params?: unknown[]): Promise<QueryResult> {
+    const rt = await boot
+    if (!rt)
+      throw new Error('useGscAnalyzer: query() requires a SQL-capable source with attachedTables; current source routes through the server')
+    return rt.query(sql, params)
+  }
+
+  async function runServerAnalyze(params: AnalysisParams, _signal?: AbortSignal): Promise<AnalysisResult & { queryMs: number }> {
+    const out = await useGscAnalyticsClient().analyze<AnalysisResult & { queryMs?: number }>(siteId, params)
+    return {
+      results: coerceResults(out.results) as AnalysisResult['results'],
+      meta: out.meta as AnalysisResult['meta'],
+      queryMs: out.queryMs ?? 0,
+    }
+  }
+
+  async function analyze(params: AnalysisParams, opts?: { signal?: AbortSignal }): Promise<AnalysisResult & { queryMs: number }> {
+    const rt = await boot
+    opts?.signal?.throwIfAborted?.()
+
+    const key = JSON.stringify(params)
+    const existing = inFlight.get(key)
+    if (existing)
+      return opts?.signal ? raceSignal(existing, opts.signal) : existing
+
+    const p = (async () => {
+      if (!rt)
+        return runServerAnalyze(params, opts?.signal)
+      const out = await rt.analyze(params as never, defaultAnalyzerRegistry)
+      opts?.signal?.throwIfAborted?.()
+      return {
+        results: coerceResults(out.results) as AnalysisResult['results'],
+        meta: out.meta as AnalysisResult['meta'],
+        queryMs: out.queryMs,
+      }
+    })()
+    inFlight.set(key, p)
+    p.finally(() => {
+      if (inFlight.get(key) === p)
+        inFlight.delete(key)
+    })
+    return opts?.signal ? raceSignal(p, opts.signal) : p
+  }
+
+  async function refresh(): Promise<boolean> {
+    await boot
+    if (mode !== 'browser-attached' || !runtime || !bootedDb)
+      return false
+    const sources = await useGscAnalyticsClient().getAnalysisSources(siteId) as AnalysisSourcesResponse
+    if (!runtime.isStale(sources.manifestVersion))
+      return false
+    // Drop the stale views before swapping in the new partitions. The runtime
+    // (db + conn) stays alive — we're swapping the data, not the engine.
+    await attachedHandle?.detach().catch((e) => {
+      console.warn('[analyzer] detach during refresh failed', e)
+    })
+    attachedHandle = null
+    await attachFromSources(sources)
+    runtime.setVersion(sources.manifestVersion)
+    runtime.setAttachedTables(attachedTables.value)
+    return true
+  }
+
+  async function dispose(): Promise<void> {
+    await runtime?.close().catch((e) => {
+      console.error('[analyzer] runtime.close failed', e)
+    })
+    runtime = null
+    bootedDb = null
+    attachedHandle = null
+    ready.value = false
+    attachedTables.value = []
+    manifestVersion.value = undefined
+    inFlight.clear()
+  }
+
+  return { ready, initializing, error, attachedTables, timings, manifestVersion, query, analyze, refresh, dispose }
+}
+
+function coerceResults(results: unknown): unknown {
+  if (!Array.isArray(results))
+    return results
+  let changed = false
+  const out: unknown[] = Array.from({ length: results.length })
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i]
+    if (r && typeof r === 'object') {
+      const c = coerceRow(r as Record<string, unknown>)
+      if (c !== r)
+        changed = true
+      out[i] = c
+    }
+    else {
+      out[i] = r
+    }
+  }
+  return changed ? out : results
+}
+
+function abortError(): DOMException {
+  return new DOMException('aborted', 'AbortError')
+}
+
+function raceSignal<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted)
+    return Promise.reject(abortError())
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => reject(abortError())
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise.then(
+      (v) => {
+        signal.removeEventListener('abort', onAbort)
+        resolve(v)
+      },
+      (e) => {
+        signal.removeEventListener('abort', onAbort)
+        reject(e)
+      },
+    )
+  })
+}

package/app/composables/useGscAnalyzerBatch.ts

@@ -0,0 +1,106 @@
+// Run N analyzers in parallel against a single analyzer runner, with per-id
+// status tracking, optional concurrency cap, and stale-token discard so
+// late-completing tasks from a superseded `run()` don't overwrite fresher state.
+//
+// Caller owns: result shaping (summarize, scoring), the trigger watcher,
+// and which ids to run.
+
+import type { MaybeRefOrGetter, Ref } from '@vue/runtime-core'
+
+export type GscAnalyzerBatchStatus = 'idle' | 'pending' | 'running' | 'done' | 'error' | 'skipped'
+
+export interface GscAnalyzerBatchEntry<TResult> {
+  status: GscAnalyzerBatchStatus
+  result: TResult | null
+  error: Error | null
+}
+
+export interface GscAnalyzerBatchRunner {
+  analyze: (params: { type: string, dateStart?: string, dateEnd?: string }) => Promise<unknown>
+}
+
+export interface UseGscAnalyzerBatchOptions {
+  /** Cap parallel analyzer runs. DuckDB-WASM is single-threaded; high parallelism just serializes behind one connection. Default 2. */
+  concurrency?: number
+  /** Drop ids before running (e.g. analyzers the current source can't serve). Returning `false` marks them `skipped`. */
+  filter?: (id: string) => boolean
+}
+
+export interface UseGscAnalyzerBatchReturn<TResult> {
+  states: Ref<Record<string, GscAnalyzerBatchEntry<TResult>>>
+  running: Ref<boolean>
+  run: () => Promise<void>
+}
+
+export function useGscAnalyzerBatch<TResult = unknown>(
+  runner: GscAnalyzerBatchRunner,
+  ids: MaybeRefOrGetter<readonly string[]>,
+  dateRange: MaybeRefOrGetter<{ start: string, end: string }>,
+  opts: UseGscAnalyzerBatchOptions = {},
+): UseGscAnalyzerBatchReturn<TResult> {
+  const states = ref<Record<string, GscAnalyzerBatchEntry<TResult>>>({}) as Ref<Record<string, GscAnalyzerBatchEntry<TResult>>>
+  const running = ref(false)
+  let token = 0
+
+  function reset(currentIds: readonly string[]): void {
+    const next: Record<string, GscAnalyzerBatchEntry<TResult>> = {}
+    for (const id of currentIds)
+      next[id] = { status: 'pending', result: null, error: null }
+    states.value = next
+  }
+
+  async function run(): Promise<void> {
+    const myToken = ++token
+    const currentIds = toValue(ids)
+    const range = toValue(dateRange)
+    running.value = true
+    reset(currentIds)
+
+    const filter = opts.filter
+    const concurrency = Math.max(1, opts.concurrency ?? 2)
+
+    const queue: string[] = []
+    for (const id of currentIds) {
+      if (filter && !filter(id))
+        states.value = { ...states.value, [id]: { status: 'skipped', result: null, error: null } }
+      else
+        queue.push(id)
+    }
+
+    async function runOne(id: string): Promise<void> {
+      if (token !== myToken)
+        return
+      states.value = { ...states.value, [id]: { status: 'running', result: null, error: null } }
+      try {
+        const result = await runner.analyze({ type: id, dateStart: range.start, dateEnd: range.end })
+        if (token !== myToken)
+          return
+        states.value = { ...states.value, [id]: { status: 'done', result: result as TResult, error: null } }
+      }
+      catch (err) {
+        if (token !== myToken)
+          return
+        const error = err instanceof Error ? err : new Error(String(err))
+        states.value = { ...states.value, [id]: { status: 'error', result: null, error } }
+      }
+    }
+
+    const workers = Array.from({ length: concurrency }, async () => {
+      while (queue.length) {
+        if (token !== myToken)
+          return
+        const id = queue.shift()
+        if (!id)
+          break
+        await runOne(id)
+      }
+    })
+
+    await Promise.all(workers)
+
+    if (token === myToken)
+      running.value = false
+  }
+
+  return { states, running, run }
+}

package/app/composables/useGscAnalyzerDefs.ts

@@ -0,0 +1,118 @@
+// Registry of analyzer definitions. The layer owns the type shape and the
+// reader; hosts provide the array via a Nuxt plugin (`$gscAnalyzers`) or via
+// the module's `analyzers` option (which generates the plugin at build time).
+//
+// Callers:
+//   - `/analyze` page builds its tab list from `useGscAnalyzerDefs()` and
+//     renders each tab via `<GscAnalyzerPanel :def>` driven by `panel`.
+//   - `/insights` page filters via `useGscAnalyzerDefsWithCapability('insightCard')`.
+//   - `useActionPriority` filters via `useGscAnalyzerDefsWithCapability('actionPriority')`.
+//
+// Capability slots are typed; e.g. `actionPriority` only accepts the
+// `ActionSource` union from `@gscdump/analysis`, so misspelt or unknown
+// sources fail at typecheck instead of at runtime in the priority runner.
+
+import type { ActionSource, AnalysisTool } from '@gscdump/analysis'
+import type { Component } from '@vue/runtime-core'
+
+export type GscAnalyzerKind = 'analyzer' | 'semantic' | 'action'
+
+export type GscAnalyzerAccent = 'primary' | 'warning' | 'success' | 'error' | 'neutral'
+
+export interface GscAnalyzerInsightCard {
+  icon: string
+  accent: GscAnalyzerAccent
+  description: string
+  summarize: (res: { results: unknown[], meta: Record<string, unknown> }) => { headline: string, tagline: string }
+}
+
+export interface GscAnalyzerStatTile {
+  label: string
+  value: string | number
+  /**
+   * Optional CSS color string for the value (used by the few panels that
+   *  color-code direction, e.g. improved/worsened in change-points).
+   */
+  valueColor?: string
+}
+
+export interface GscAnalyzerPanelResult {
+  results: unknown[]
+  meta: Record<string, unknown>
+  queryMs?: number | null
+}
+
+export interface GscAnalyzerPanelSpec {
+  /**
+   * Body component. Receives `{ rows, meta, range }` as props. Lazy-import
+   *  via `defineAsyncComponent(() => import(...))` to preserve route-level
+   *  codesplitting — pages that don't render the analyzer never pay for its
+   *  chart code.
+   */
+  component: Component
+  /** Project a result to the header stat tiles. Empty array = no tiles. */
+  summarize?: (res: GscAnalyzerPanelResult) => GscAnalyzerStatTile[]
+  /** Italic footer caption explaining the underlying method. */
+  caption?: string
+  /**
+   * When true, the shell skips its loading/error/empty gating and renders
+   *  the body component immediately — the panel manages its own phase state
+   *  (pipeline panels: action priority, content gap).
+   */
+  ownsLifecycle?: boolean
+}
+
+export interface GscAnalyzerCapabilities {
+  /** Opt into the `/insights` curated grid by providing a card config. */
+  insightCard?: GscAnalyzerInsightCard
+  /** Opt into `useActionPriority`. The value is the typed `ActionSource` slug. */
+  actionPriority?: ActionSource
+  /**
+   * Opt into the unified `/analyze` panel renderer. Without this, the tab
+   *  falls back to the generic table renderer in `<GscAnalyzerPanel>`.
+   */
+  panel?: GscAnalyzerPanelSpec
+}
+
+export type GscAnalyzerCapability = keyof GscAnalyzerCapabilities
+
+export interface GscAnalyzerDefinition {
+  /** Stable analyzer id. Must match an `AnalysisTool` slug for built-in analyzers. */
+  id: AnalysisTool | (string & {})
+  label: string
+  kind: GscAnalyzerKind
+  /** Reads the per-query table; sums silently drop GSC-anonymized impressions. */
+  isQueryGrained?: boolean
+  /** Capability opt-ins. Each key gates a downstream consumer. */
+  capabilities?: GscAnalyzerCapabilities
+}
+
+export type GscAnalyzerDefinitionWithCapability<K extends GscAnalyzerCapability>
+  = GscAnalyzerDefinition & {
+    capabilities: { [P in K]: NonNullable<GscAnalyzerCapabilities[P]> }
+  }
+
+export function defineGscAnalyzer(def: GscAnalyzerDefinition): GscAnalyzerDefinition {
+  return def
+}
+
+export function useGscAnalyzerDefs(): GscAnalyzerDefinition[] {
+  return (useNuxtApp().$gscAnalyzers as GscAnalyzerDefinition[] | undefined) ?? []
+}
+
+export function useGscAnalyzerDef(id: string): GscAnalyzerDefinition | undefined {
+  return useGscAnalyzerDefs().find(a => a.id === id)
+}
+
+/**
+ * Typed filter that narrows defs to those with `capability` opted in.
+ * The returned defs have `capabilities[capability]` typed as non-nullable.
+ */
+export function useGscAnalyzerDefsWithCapability<K extends GscAnalyzerCapability>(
+  capability: K,
+): GscAnalyzerDefinitionWithCapability<K>[] {
+  return useGscAnalyzerDefs().filter(
+    (d): d is GscAnalyzerDefinitionWithCapability<K> =>
+      d.capabilities?.[capability] != null,
+  )
+}