@nitpicker/crawler 0.8.0 → 0.11.0

package/lib/archive/meta/compare-semver.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Compares two semver-like version strings.
+ *
+ * Only the major / minor / patch numeric components are considered;
+ * pre-release tags (`-alpha.1`) and build metadata (`+sha.abc`) are
+ * dropped before comparison so `"0.10.0-alpha.1"` compares equal to
+ * `"0.10.0"`. Missing components default to `0`, so `"0.10"` compares
+ * equal to `"0.10.0"`.
+ *
+ * Designed for `assertCompatibleVersion`'s
+ * "is the archive's `info.version` at least the required format
+ * version?" check — we do not need full semver semantics there, and
+ * pulling in the `semver` package would be overkill for one numeric
+ * comparison.
+ * @param a - The left-hand version string.
+ * @param b - The right-hand version string.
+ * @returns Negative when `a < b`, positive when `a > b`, zero when equal.
+ * @example
+ * compareSemver('0.9.0', '0.10.0')          // → -1
+ * compareSemver('0.10.0', '0.10.0')         // → 0
+ * compareSemver('0.10.5-alpha.1', '0.10.0') // → +5
+ */
+export declare function compareSemver(a: string, b: string): number;

package/lib/archive/meta/compare-semver.js

@@ -0,0 +1,51 @@
+/**
+ * Compares two semver-like version strings.
+ *
+ * Only the major / minor / patch numeric components are considered;
+ * pre-release tags (`-alpha.1`) and build metadata (`+sha.abc`) are
+ * dropped before comparison so `"0.10.0-alpha.1"` compares equal to
+ * `"0.10.0"`. Missing components default to `0`, so `"0.10"` compares
+ * equal to `"0.10.0"`.
+ *
+ * Designed for `assertCompatibleVersion`'s
+ * "is the archive's `info.version` at least the required format
+ * version?" check — we do not need full semver semantics there, and
+ * pulling in the `semver` package would be overkill for one numeric
+ * comparison.
+ * @param a - The left-hand version string.
+ * @param b - The right-hand version string.
+ * @returns Negative when `a < b`, positive when `a > b`, zero when equal.
+ * @example
+ * compareSemver('0.9.0', '0.10.0')          // → -1
+ * compareSemver('0.10.0', '0.10.0')         // → 0
+ * compareSemver('0.10.5-alpha.1', '0.10.0') // → +5
+ */
+export function compareSemver(a, b) {
+    const pa = parseComponents(a);
+    const pb = parseComponents(b);
+    for (let i = 0; i < 3; i++) {
+        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * Strips pre-release / build metadata and parses the first three numeric
+ * components. Missing components default to `0`. Non-numeric components
+ * collapse to `0` rather than throwing — `assertCompatibleVersion` needs
+ * defensive behavior against hand-edited `info.version` strings.
+ * @param version
+ */
+function parseComponents(version) {
+    const core = version.split(/[-+]/)[0] ?? '';
+    const parts = core.split('.');
+    const major = Number.parseInt(parts[0] ?? '0', 10);
+    const minor = Number.parseInt(parts[1] ?? '0', 10);
+    const patch = Number.parseInt(parts[2] ?? '0', 10);
+    return [
+        Number.isFinite(major) ? major : 0,
+        Number.isFinite(minor) ? minor : 0,
+        Number.isFinite(patch) ? patch : 0,
+    ];
+}

package/lib/archive/meta/compute-page-denormalized.d.ts

@@ -0,0 +1,21 @@
+import type { PageDenormalizedColumns } from './types.js';
+import type { Meta } from '@d-zero/beholder';
+/**
+ * Computes the denormalised aggregate columns stored on the `pages` table at
+ * write time: `tag_count`, `jsonld_count`, `tags_providers_csv`.
+ *
+ * Why denormalise: the Sheets report and the `get-page-detail` summary need
+ * "how many JSON-LD entries?" and "which Wappalyzer providers?" for every
+ * page row. Computing those at read time forces either a per-page sub-query
+ * (N+1) or a site-wide `GROUP BY` (heavy on 1M-page archives). Writing them
+ * once at scrape time keeps the read path to a single `pages` projection.
+ *
+ * `tags_providers_csv` uses comma as separator (no escaping). Wappalyzer
+ * provider names do not contain commas in practice; if that ever changes,
+ * switch to a JSON array column or use `\x1f` as separator. The CSV form
+ * exists because Sheets / Google Spreadsheet renders comma-separated lists
+ * natively without unwrapping JSON.
+ * @param meta - Beholder-derived metadata for the page.
+ * @returns The three denormalised columns.
+ */
+export declare function computePageDenormalized(meta: Meta): PageDenormalizedColumns;

package/lib/archive/meta/compute-page-denormalized.js

@@ -0,0 +1,35 @@
+/**
+ * Computes the denormalised aggregate columns stored on the `pages` table at
+ * write time: `tag_count`, `jsonld_count`, `tags_providers_csv`.
+ *
+ * Why denormalise: the Sheets report and the `get-page-detail` summary need
+ * "how many JSON-LD entries?" and "which Wappalyzer providers?" for every
+ * page row. Computing those at read time forces either a per-page sub-query
+ * (N+1) or a site-wide `GROUP BY` (heavy on 1M-page archives). Writing them
+ * once at scrape time keeps the read path to a single `pages` projection.
+ *
+ * `tags_providers_csv` uses comma as separator (no escaping). Wappalyzer
+ * provider names do not contain commas in practice; if that ever changes,
+ * switch to a JSON array column or use `\x1f` as separator. The CSV form
+ * exists because Sheets / Google Spreadsheet renders comma-separated lists
+ * natively without unwrapping JSON.
+ * @param meta - Beholder-derived metadata for the page.
+ * @returns The three denormalised columns.
+ */
+export function computePageDenormalized(meta) {
+    // `??` guards tolerate the legacy "minimal meta" shape (`{ title: 'X' }`)
+    // produced by older test fixtures. Real beholder 3.0.0 always populates
+    // these required fields; the guards only matter for test fixtures that
+    // pre-date the v2 schema.
+    const tagEntries = meta.tags?.entries ?? [];
+    const jsonLd = meta.jsonLd ?? [];
+    const speculationRules = meta.speculationRules ?? [];
+    const tag_count = tagEntries.length;
+    const jsonld_count = jsonLd.length + speculationRules.length;
+    const providers = new Set();
+    for (const entry of tagEntries) {
+        providers.add(entry.provider);
+    }
+    const tags_providers_csv = [...providers].toSorted().join(',');
+    return { tag_count, jsonld_count, tags_providers_csv };
+}

package/lib/archive/meta/derive-flat-from-meta.d.ts

@@ -0,0 +1,35 @@
+import type { FlatPageMetaColumns } from './types.js';
+import type { Meta } from '@d-zero/beholder';
+/**
+ * Derives the {@link FlatPageMetaColumns} (`pages` table flat columns) from a
+ * beholder {@link Meta} object.
+ *
+ * Handles three concerns the database layer should not re-implement:
+ *
+ * 1. **Null-safe traversal** of the new nested Meta shape
+ *    (`meta.og?.title`, `meta.robots?.noindex`, `meta.link?.canonical`, etc.).
+ *    All optional sub-objects are guarded so an absent meta tag becomes
+ *    `null` rather than a runtime crash.
+ *
+ * 2. **URL absolutisation** for every URL-shaped column. beholder 3.0.0
+ *    extracts link/og href values via `link.getAttribute('href')`, which
+ *    preserves relative URLs as-written. `find-mismatches` compares
+ *    `canonical != url` directly, so we must resolve everything against the
+ *    page URL (or `<base href>` if present) before persistence. Malformed
+ *    URLs become `null` rather than blowing up the entire insert.
+ *
+ * 3. **Boolean → integer coercion** for SQLite-style boolean columns
+ *    (`robots_*`, `formatDetection_telephone`). `undefined` and unparseable
+ *    values map to `null`.
+ *
+ * URL-shaped columns: `canonical`, `og_url`, `og_image`, `amphtml`,
+ * `manifest`, `icon_href`, `appleTouchIcon_href`, `twitter_image`.
+ * @param meta - Beholder-derived metadata for the page.
+ * @param pageUrl - Absolute URL of the page being persisted. Used as the
+ *   fallback base when `meta.baseHref` is absent or relative.
+ * @returns A flat object whose keys map 1:1 to `pages` table columns.
+ * @example
+ * deriveFlatFromMeta(meta, 'https://example.com/about')
+ *   // → { canonical: 'https://example.com/about', og_title: '...', ... }
+ */
+export declare function deriveFlatFromMeta(meta: Meta, pageUrl: string): FlatPageMetaColumns;

package/lib/archive/meta/derive-flat-from-meta.js

@@ -0,0 +1,158 @@
+/**
+ * Derives the {@link FlatPageMetaColumns} (`pages` table flat columns) from a
+ * beholder {@link Meta} object.
+ *
+ * Handles three concerns the database layer should not re-implement:
+ *
+ * 1. **Null-safe traversal** of the new nested Meta shape
+ *    (`meta.og?.title`, `meta.robots?.noindex`, `meta.link?.canonical`, etc.).
+ *    All optional sub-objects are guarded so an absent meta tag becomes
+ *    `null` rather than a runtime crash.
+ *
+ * 2. **URL absolutisation** for every URL-shaped column. beholder 3.0.0
+ *    extracts link/og href values via `link.getAttribute('href')`, which
+ *    preserves relative URLs as-written. `find-mismatches` compares
+ *    `canonical != url` directly, so we must resolve everything against the
+ *    page URL (or `<base href>` if present) before persistence. Malformed
+ *    URLs become `null` rather than blowing up the entire insert.
+ *
+ * 3. **Boolean → integer coercion** for SQLite-style boolean columns
+ *    (`robots_*`, `formatDetection_telephone`). `undefined` and unparseable
+ *    values map to `null`.
+ *
+ * URL-shaped columns: `canonical`, `og_url`, `og_image`, `amphtml`,
+ * `manifest`, `icon_href`, `appleTouchIcon_href`, `twitter_image`.
+ * @param meta - Beholder-derived metadata for the page.
+ * @param pageUrl - Absolute URL of the page being persisted. Used as the
+ *   fallback base when `meta.baseHref` is absent or relative.
+ * @returns A flat object whose keys map 1:1 to `pages` table columns.
+ * @example
+ * deriveFlatFromMeta(meta, 'https://example.com/about')
+ *   // → { canonical: 'https://example.com/about', og_title: '...', ... }
+ */
+export function deriveFlatFromMeta(meta, pageUrl) {
+    const base = resolveBase(meta.baseHref, pageUrl);
+    const robots = meta.robots;
+    const og = meta.og;
+    const ogArticle = og?.article;
+    const twitter = meta.twitter;
+    const link = meta.link;
+    const formatDetection = meta.formatDetection;
+    return {
+        // Document basics
+        lang: nullableString(meta.lang),
+        dir: nullableString(meta.dir),
+        charset: nullableString(meta.charset),
+        baseHref: absolutizeUrl(meta.baseHref, pageUrl),
+        viewport_raw: nullableString(meta.viewport?.raw),
+        themeColor: nullableString(meta.themeColor),
+        applicationName: nullableString(meta.applicationName),
+        author: nullableString(meta.author),
+        generator: nullableString(meta.generator),
+        publisher: nullableString(meta.publisher),
+        // Robots
+        robots_raw: nullableString(robots?.raw),
+        robots_noindex: booleanToInt(robots?.noindex),
+        robots_nofollow: booleanToInt(robots?.nofollow),
+        robots_noarchive: booleanToInt(robots?.noarchive),
+        robots_noimageindex: booleanToInt(robots?.noimageindex),
+        googlebot: nullableString(meta.googlebot),
+        // Link (1:1 only)
+        canonical: absolutizeUrl(link?.canonical, base),
+        amphtml: absolutizeUrl(link?.amphtml, base),
+        manifest: absolutizeUrl(link?.manifest, base),
+        icon_href: absolutizeUrl(link?.icon?.href, base),
+        appleTouchIcon_href: absolutizeUrl(link?.appleTouchIcon?.href, base),
+        // Open Graph
+        og_type: nullableString(og?.type),
+        og_title: nullableString(og?.title),
+        og_url: absolutizeUrl(og?.url, base),
+        og_site_name: nullableString(og?.siteName),
+        og_description: nullableString(og?.description),
+        og_image: absolutizeUrl(og?.imageUrl ?? og?.image?.[0], base),
+        og_image_alt: nullableString(og?.imageAlt),
+        og_image_width: nullableString(og?.imageWidth),
+        og_image_height: nullableString(og?.imageHeight),
+        og_locale: nullableString(og?.locale),
+        og_article_published_time: nullableString(ogArticle?.publishedTime),
+        og_article_modified_time: nullableString(ogArticle?.modifiedTime),
+        // Twitter
+        twitter_card: nullableString(twitter?.card),
+        twitter_site: nullableString(twitter?.site),
+        twitter_creator: nullableString(twitter?.creator),
+        twitter_title: nullableString(twitter?.title),
+        twitter_description: nullableString(twitter?.description),
+        twitter_image: absolutizeUrl(twitter?.image ?? twitter?.imageSrc, base),
+        // One-offs
+        fb_app_id: nullableString(meta.fb?.appId),
+        verification_google: nullableString(meta.verification?.google),
+        formatDetection_telephone: booleanToInt(formatDetection?.telephone),
+        // Title / description / keywords (top-level Meta fields)
+        title: nullableString(meta.title),
+        description: nullableString(meta.description),
+        keywords: nullableString(meta.keywords),
+    };
+}
+/**
+ * Resolves the effective base URL for relative-URL absolutisation.
+ *
+ * Falls back to `pageUrl` when `baseHref` is absent. When `baseHref` itself
+ * is a relative URL (rare but spec-permitted), resolves it against
+ * `pageUrl` first so subsequent `new URL(value, base)` calls see an
+ * absolute base.
+ * @param baseHref
+ * @param pageUrl
+ */
+function resolveBase(baseHref, pageUrl) {
+    if (!baseHref)
+        return pageUrl;
+    try {
+        return new URL(baseHref, pageUrl).href;
+    }
+    catch {
+        return pageUrl;
+    }
+}
+/**
+ * Resolves a possibly-relative URL against a base.
+ *
+ * Returns `null` for `undefined` / empty string / unparseable input so a
+ * malformed page does not abort the entire `#insertPage` call.
+ * @param value
+ * @param base
+ */
+function absolutizeUrl(value, base) {
+    if (value === undefined || value === null || value === '')
+        return null;
+    try {
+        return new URL(value, base).href;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Normalises optional / empty strings to `null` so SQL `IS NULL` queries
+ * behave consistently. Trim is intentional — leading/trailing whitespace in
+ * `<meta content=>` is meaningless for downstream consumers.
+ * @param value
+ */
+function nullableString(value) {
+    if (value === undefined || value === null)
+        return null;
+    const trimmed = value.trim();
+    return trimmed === '' ? null : trimmed;
+}
+/**
+ * Converts an optional boolean to SQLite's 0/1 integer representation. Any
+ * non-boolean (`undefined`, non-boolean string from `boolean-true` keys)
+ * becomes `null`.
+ * @param value
+ */
+function booleanToInt(value) {
+    if (value === true)
+        return 1;
+    if (value === false)
+        return 0;
+    return null;
+}

package/lib/archive/meta/derive-meta-extras.d.ts

@@ -0,0 +1,20 @@
+import type { Meta } from '@d-zero/beholder';
+/**
+ * Derives the `meta_extras` JSON payload from a beholder {@link Meta} object.
+ *
+ * Strategy: pass-through everything except data that lives in dedicated
+ * tables (`page_jsonld`, `page_tags`) or that is debug-only
+ * (`_raw`). Flat columns are intentionally **not** stripped — the modest
+ * storage duplication is preferred over a fragile field-by-field denylist
+ * that breaks every time beholder grows new Meta fields.
+ *
+ * The output is JSON-stringified by the caller (`#insertPage`) and stored in
+ * `pages.meta_extras`. Consumers read it back via `get-page-detail` and the
+ * Page wrapper's `metaExtras` getter.
+ *
+ * Plan note: "ファイルサイズが多少増えてもいいから取り出しパフォーマンスを優先" — this is exactly that
+ * trade-off. Future Meta fields are auto-captured without code change.
+ * @param meta - Beholder-derived metadata for the page.
+ * @returns Plain object suitable for `JSON.stringify`.
+ */
+export declare function deriveMetaExtras(meta: Meta): Record<string, unknown>;

package/lib/archive/meta/derive-meta-extras.js

@@ -0,0 +1,23 @@
+/**
+ * Derives the `meta_extras` JSON payload from a beholder {@link Meta} object.
+ *
+ * Strategy: pass-through everything except data that lives in dedicated
+ * tables (`page_jsonld`, `page_tags`) or that is debug-only
+ * (`_raw`). Flat columns are intentionally **not** stripped — the modest
+ * storage duplication is preferred over a fragile field-by-field denylist
+ * that breaks every time beholder grows new Meta fields.
+ *
+ * The output is JSON-stringified by the caller (`#insertPage`) and stored in
+ * `pages.meta_extras`. Consumers read it back via `get-page-detail` and the
+ * Page wrapper's `metaExtras` getter.
+ *
+ * Plan note: "ファイルサイズが多少増えてもいいから取り出しパフォーマンスを優先" — this is exactly that
+ * trade-off. Future Meta fields are auto-captured without code change.
+ * @param meta - Beholder-derived metadata for the page.
+ * @returns Plain object suitable for `JSON.stringify`.
+ */
+export function deriveMetaExtras(meta) {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- we destructure to omit these from the spread
+    const { jsonLd, speculationRules, tags, _raw, ...rest } = meta;
+    return rest;
+}

package/lib/archive/meta/extract-tags-for-archive.d.ts

@@ -0,0 +1,18 @@
+import type { TagRowForInsert } from './types.js';
+import type { TagsMeta } from '@d-zero/beholder';
+/**
+ * Flattens {@link TagsMeta.entries} (per provider × external-id tuple) into
+ * insert-ready rows for the `page_tags` table.
+ *
+ * One Wappalyzer entry → one row. `entry.id` becomes `externalId`. `category`
+ * is the first element of `categories`; the full list is preserved in the
+ * `categories` JSON column. `sources` is preserved verbatim as a JSON column.
+ *
+ * `pageId` is **not** filled here — the database layer injects it because the
+ * page row is `INSERT`-ed in the same transaction and its ID is known only at
+ * insert time.
+ * @param tags - The `meta.tags` object from beholder.
+ * @returns Rows ready for the `page_tags` insert; empty array when no tags
+ *   were detected.
+ */
+export declare function extractTagsForArchive(tags: TagsMeta | undefined): ReadonlyArray<Omit<TagRowForInsert, 'pageId'>>;

package/lib/archive/meta/extract-tags-for-archive.js

@@ -0,0 +1,36 @@
+/**
+ * Flattens {@link TagsMeta.entries} (per provider × external-id tuple) into
+ * insert-ready rows for the `page_tags` table.
+ *
+ * One Wappalyzer entry → one row. `entry.id` becomes `externalId`. `category`
+ * is the first element of `categories`; the full list is preserved in the
+ * `categories` JSON column. `sources` is preserved verbatim as a JSON column.
+ *
+ * `pageId` is **not** filled here — the database layer injects it because the
+ * page row is `INSERT`-ed in the same transaction and its ID is known only at
+ * insert time.
+ * @param tags - The `meta.tags` object from beholder.
+ * @returns Rows ready for the `page_tags` insert; empty array when no tags
+ *   were detected.
+ */
+export function extractTagsForArchive(tags) {
+    // `tags` can be undefined when fed legacy minimal-Meta test fixtures.
+    // Real beholder 3.0.0 always populates this required field.
+    const entries = tags?.entries ?? [];
+    if (entries.length === 0)
+        return [];
+    return entries.map((entry) => ({
+        provider: entry.provider,
+        category: entry.categories[0] ?? null,
+        externalId: entry.id ?? null,
+        version: entry.version ?? null,
+        confidence: entry.confidence ?? null,
+        categories: [...entry.categories],
+        sources: entry.sources.map((s) => ({
+            type: s.type,
+            src: s.src,
+            location: s.location,
+            globalName: s.globalName,
+        })),
+    }));
+}

package/lib/archive/meta/summarize-jsonld.d.ts

@@ -0,0 +1,17 @@
+import type { JsonLdRow, JsonLdSummary } from './types.js';
+/**
+ * Builds the {@link JsonLdSummary} object returned by `get-page-detail` from a
+ * page's JSON-LD rows.
+ *
+ * Why summary: the raw payload of a single page's JSON-LD can reach several
+ * MB on e-commerce sites (Amazon product page = 50 schemas × 50KB). Returning
+ * that inline blows up MCP / LLM token budgets. The summary preserves the
+ * shape of the data (counts + unique types + parse error count) so consumers
+ * can decide whether to drill in via `get-page-jsonld(url)`.
+ *
+ * Entries with `type === null` are surfaced as `'(unknown)'` so the type
+ * list is enumerable without sentinel handling on the consumer side.
+ * @param rows - All `page_jsonld` rows for one page.
+ * @returns Summary with `count`, sorted unique `types[]`, and `parseErrorCount`.
+ */
+export declare function summarizeJsonLd(rows: readonly JsonLdRow[]): JsonLdSummary;

package/lib/archive/meta/summarize-jsonld.js

@@ -0,0 +1,29 @@
+/**
+ * Builds the {@link JsonLdSummary} object returned by `get-page-detail` from a
+ * page's JSON-LD rows.
+ *
+ * Why summary: the raw payload of a single page's JSON-LD can reach several
+ * MB on e-commerce sites (Amazon product page = 50 schemas × 50KB). Returning
+ * that inline blows up MCP / LLM token budgets. The summary preserves the
+ * shape of the data (counts + unique types + parse error count) so consumers
+ * can decide whether to drill in via `get-page-jsonld(url)`.
+ *
+ * Entries with `type === null` are surfaced as `'(unknown)'` so the type
+ * list is enumerable without sentinel handling on the consumer side.
+ * @param rows - All `page_jsonld` rows for one page.
+ * @returns Summary with `count`, sorted unique `types[]`, and `parseErrorCount`.
+ */
+export function summarizeJsonLd(rows) {
+    const types = new Set();
+    let parseErrorCount = 0;
+    for (const row of rows) {
+        types.add(row.type ?? '(unknown)');
+        if (row.parseError !== null)
+            parseErrorCount++;
+    }
+    return {
+        count: rows.length,
+        types: [...types].toSorted(),
+        parseErrorCount,
+    };
+}

package/lib/archive/meta/summarize-tags.d.ts

@@ -0,0 +1,16 @@
+import type { TagRow, TagsSummary } from './types.js';
+/**
+ * Builds the {@link TagsSummary} object returned by `get-page-detail` from a
+ * page's tag rows.
+ *
+ * Provides a `provider → unique IDs[]` map so consumers can answer questions
+ * like "what GTM containers are on this page?" without fetching the full
+ * `categories` / `sources` JSON columns.
+ *
+ * IDs within each provider are sorted and de-duplicated. Providers with no
+ * `externalId` rows still appear in the map with an empty `[]` so the
+ * caller knows the provider was detected.
+ * @param rows - All `page_tags` rows for one page.
+ * @returns Summary with `count` and `providerIds` map.
+ */
+export declare function summarizeTags(rows: readonly TagRow[]): TagsSummary;

package/lib/archive/meta/summarize-tags.js

@@ -0,0 +1,33 @@
+/**
+ * Builds the {@link TagsSummary} object returned by `get-page-detail` from a
+ * page's tag rows.
+ *
+ * Provides a `provider → unique IDs[]` map so consumers can answer questions
+ * like "what GTM containers are on this page?" without fetching the full
+ * `categories` / `sources` JSON columns.
+ *
+ * IDs within each provider are sorted and de-duplicated. Providers with no
+ * `externalId` rows still appear in the map with an empty `[]` so the
+ * caller knows the provider was detected.
+ * @param rows - All `page_tags` rows for one page.
+ * @returns Summary with `count` and `providerIds` map.
+ */
+export function summarizeTags(rows) {
+    const providerIds = {};
+    for (const row of rows) {
+        if (!(row.provider in providerIds)) {
+            providerIds[row.provider] = new Set();
+        }
+        if (row.externalId !== null) {
+            providerIds[row.provider].add(row.externalId);
+        }
+    }
+    const sorted = {};
+    for (const provider of Object.keys(providerIds).toSorted()) {
+        sorted[provider] = [...providerIds[provider]].toSorted();
+    }
+    return {
+        count: rows.length,
+        providerIds: sorted,
+    };
+}