@toolpath/tool-scraper 2.3.0 → 2.5.0

package/dist/node/cli.js

@@ -32,7 +32,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { ScraperConfigError, VendorResponseError } from '../errors.js';
 import { familyBrand } from '../family.js';
-import { ALL_FAMILIES, FAMILIES, HOLDER_FAMILIES, familyConfig } from '../families/index.js';
+import { ALL_FAMILIES, COLLET_FAMILIES, FAMILIES, HOLDER_FAMILIES, familyConfig, } from '../families/index.js';
 import { createFetcher } from '../fetch.js';
 import { buildProfiles } from '../profiles.js';
 import { AEM_BRANDS } from '../identity.js';
@@ -45,6 +45,7 @@ import { describeRoot, familyCsv, profilesDir, profilesJson, stepDir } from './p
 import * as receipts from './receipts.js';
 import { scrapeFamily } from '../vendors/kennametal/scrape.js';
 import { annotateCadUrls } from '../vendors/kennametal/cad.js';
+import { COLLET_CATEGORIES, describeFamily, discoverFamilies, } from '../vendors/kennametal/catalog.js';
 import { addMaterialGroups, groupsByMaterial } from '../vendors/kennametal/materials.js';
 import { addThreadPitch } from '../vendors/kennametal/thread-column.js';
 import { scrapeEndMills, DOCUMENTS_URL } from '../vendors/destinytool/scrape.js';
@@ -95,6 +96,12 @@ const USAGE = `usage: toolpath-scrape <command> [args]
       every row as constant columns, for facts the vendor table does not state
       (e.g. "Thread System=metric").
 
+  kennametal --collets
+      Walks the three ER collet category trees and prints every family they
+      link to today — code, slug, category, and the configured CSV that claims
+      the code or "(not configured)". For noticing a family Kennametal has
+      added, split or retired; a scrape needs none of it.
+
   regofix holders OUT.csv
   regofix collets "<PRODUCT GROUP>" OUT.csv
       The REGO-FIX ProductFinder index. \`holders\` takes every powRgrip BT/PG
@@ -265,6 +272,22 @@ export async function run(argv, io = STDOUT, fetcher = createFetcher(), api) {
             return 2;
     }
 }
+/**
+ * The configured CSV that claims each `familyCode`, for the walk to reconcile
+ * against.
+ *
+ * Toolholding only. A cutting-tool family states a code too, but the walk this
+ * serves covers the collet categories and reporting a drill family's code
+ * against a collet listing would be an answer to a question nobody asked.
+ */
+function claimedCodes() {
+    const claimed = new Map();
+    for (const [name, cfg] of Object.entries({ ...HOLDER_FAMILIES, ...COLLET_FAMILIES })) {
+        if (cfg.familyCode !== undefined)
+            claimed.set(cfg.familyCode, name);
+    }
+    return claimed;
+}
 async function kennametal(argv, io, fetcher) {
     const args = [...argv];
     let brand = 'kennametal';
@@ -285,6 +308,28 @@ async function kennametal(argv, io, fetcher) {
         io.error(`unknown brand: ${brand} (known: ${[...AEM_BRANDS].sort().join(', ')})`);
         return 2;
     }
+    if (args[0] === '--collets') {
+        const claimed = claimedCodes();
+        const found = await discoverFamilies(fetcher, COLLET_CATEGORIES, {
+            warn: io.error,
+            brand: brand,
+        });
+        let families = 0;
+        let missing = 0;
+        for (const category of found) {
+            io.log(`${category.name}: ${category.total} parts, ${category.families.length} families`);
+            for (const family of category.families) {
+                const where = claimed.get(family.code) ?? null;
+                if (where === null)
+                    missing += 1;
+                families += 1;
+                io.log(`  ${describeFamily(category, family, where)}`);
+            }
+        }
+        io.log(`${families} families under ${COLLET_CATEGORIES.length} category trees, ` +
+            `${missing} not configured`);
+        return 0;
+    }
     if (args.length < 2) {
         io.error(USAGE);
         return 2;

package/dist/records.d.ts

@@ -42,7 +42,7 @@
  * always a copy is not a second measurement. An adapter that could supply them
  * separately could supply a tool that claims a holder it does not have.
  */
-import { type UnitSystem } from '@toolpath/tool-support';
+import { type ThreadMethod, type UnitSystem } from '@toolpath/tool-support';
 import { type BrandName } from './identity.js';
 import type { FactSource } from './provenance.js';
 /**
@@ -69,6 +69,16 @@ export interface GeometryField {
      */
     iso: string | null;
 }
+/**
+ * How a tap makes its thread.
+ *
+ * `@toolpath/tool-support`'s, re-exported under the name this package reads it
+ * by — the move `conventions.ts` makes for `UnitSystem` and `provenance.ts` for
+ * `PROVENANCE`. A scrape originates the fact and the domain owns the
+ * vocabulary, and two declarations of the same two strings is the drift that
+ * rule exists to prevent.
+ */
+export type { ThreadMethod } from '@toolpath/tool-support';
 /** The kinds of cutting tool this package maps. */
 export type ToolKind = 'drill' | 'tap' | 'endmill';
 /**
@@ -447,6 +457,23 @@ export interface ToolRecord {
      * a PCD tool.
      */
     readonly nonFerrous: boolean | null;
+    /**
+     * Taps only, and `null` on every other kind because the question does not
+     * apply — the shape {@link ToolRecord.nonFerrous} already keeps for drills.
+     *
+     * **Not a default, and not derivable from anything else on the record.** A
+     * former and a cut tap of the same size share their `DC`, `TP`, `SFDM`,
+     * `OAL` and `LCF`; what separates them is that one displaces material and the
+     * other removes it, which changes the hole a shop drills first and the feed
+     * it runs. Guessing `cutting` because most of a catalog is would ship a
+     * former with a cut tap's drill size.
+     *
+     * It is a per-family fact rather than a column, and each of the five
+     * declarations cites the vendor's own index — see `families/kennametal.ts`
+     * and `families/emuge.ts`. The invariant below is what stops a sixth tap
+     * family arriving without one.
+     */
+    readonly threadMethod: ThreadMethod | null;
 }
 /**
  * Build a {@link ToolRecord}: mint its guid, default the fields that have a
@@ -473,7 +500,7 @@ export interface ToolRecord {
  * interchange value, and a mapper that mutated one would be reaching back
  * across the seam this type exists to draw.
  */
-export declare function toolRecord(fields: Omit<ToolRecord, 'guid' | 'materialGroups' | 'materialGroupsSource' | 'nonFerrous' | 'productLine'> & Partial<Pick<ToolRecord, 'materialGroups' | 'materialGroupsSource' | 'nonFerrous' | 'productLine'>>): ToolRecord;
+export declare function toolRecord(fields: Omit<ToolRecord, 'guid' | 'materialGroups' | 'materialGroupsSource' | 'nonFerrous' | 'productLine' | 'threadMethod'> & Partial<Pick<ToolRecord, 'materialGroups' | 'materialGroupsSource' | 'nonFerrous' | 'productLine' | 'threadMethod'>>): ToolRecord;
 /**
  * A family's canonical-field → CSV-column-label mapping, validated.
  *

package/dist/records.js

@@ -42,7 +42,7 @@
  * always a copy is not a second measurement. An adapter that could supply them
  * separately could supply a tool that claims a holder it does not have.
  */
-import { GEOMETRY_FIELDS as DICTIONARY } from '@toolpath/tool-support';
+import { GEOMETRY_FIELDS as DICTIONARY, } from '@toolpath/tool-support';
 import { dimensionalColumn } from './conventions.js';
 import { ScraperConfigError } from './errors.js';
 import { recordGuid } from './identity.js';
@@ -315,9 +315,21 @@ export function toolRecord(fields) {
             `and materialGroupsSource is ${JSON.stringify(source)} — ` +
             `groups are ${JSON.stringify(UNSPECIFIED)} exactly when there are none`);
     }
+    // A tap says how it makes its thread and nothing else does. Both halves are
+    // load-bearing: a tap record with no method is a family that never declared
+    // the fact, and a method on a drill is a mapper that copied a line from the
+    // tap one. Neither can be recovered downstream from what is left on the
+    // record, because the geometry of a former and a cut tap is the same
+    // geometry.
+    const method = fields.threadMethod ?? null;
+    if ((fields.kind === 'tap') !== (method !== null)) {
+        throw new ScraperConfigError(fields.materialNumber, `a ${fields.kind} record states threadMethod ${JSON.stringify(method)} — ` +
+            `a tap says how it makes its thread and no other kind does`);
+    }
     checkGeometry(fields.kind, fields.materialNumber, fields.geometry);
     return Object.freeze({
         ...fields,
+        threadMethod: method,
         guid: recordGuid(fields.brand, fields.materialNumber),
         geometry: Object.freeze({ ...fields.geometry }),
         materialGroups: groups === null ? null : Object.freeze([...groups]),

package/dist/vendors/emuge/records.d.ts

@@ -155,6 +155,16 @@ export declare const PRODUCT_LINE_COLUMNS: Readonly<Record<string, string>>;
  * vendor's marketing rather than a hole here: `SPEED`, `FK`, `GAL`, `GG` and
  * `TILEG` are real lines with no `/a/` page on the US storefront, so the
  * honest answer is the vendor's own code until one appears.
+ *
+ * **`FG02` has no entry at all, on purpose.** Cold-forming taps index by the
+ * same eight geometry codes `FG01` uses — `AL`, `GAL`, `H`, `MULTI`, `SPEED`,
+ * `STEEL`, `VA`, `Z` — and mean different products by them: a `Z`-geometry
+ * former is InnoForm, not the `Rekord B-Z Taps` the `FG01` table would name it.
+ * Borrowing that table would put a cutting tap's product line on a forming tap,
+ * which is the one error this category split exists to make impossible. So the
+ * codes pass through verbatim, which is what the paragraph above already says a
+ * code with no article page does, and naming them from the vendor's own
+ * cold-forming pages is the follow-up.
  */
 export declare const PRODUCT_LINES: Readonly<Record<string, Readonly<Record<string, string>>>>;
 /**

package/dist/vendors/emuge/records.js

@@ -172,6 +172,7 @@ export const PRODUCT_LINE_COLUMNS = {
     FF01: 'product line',
     FB01: 'Geometry',
     FG01: 'Geometry',
+    FG02: 'Geometry',
 };
 /**
  * A category's product-line codes onto the vendor's own name for each.
@@ -194,6 +195,16 @@ export const PRODUCT_LINE_COLUMNS = {
  * vendor's marketing rather than a hole here: `SPEED`, `FK`, `GAL`, `GG` and
  * `TILEG` are real lines with no `/a/` page on the US storefront, so the
  * honest answer is the vendor's own code until one appears.
+ *
+ * **`FG02` has no entry at all, on purpose.** Cold-forming taps index by the
+ * same eight geometry codes `FG01` uses — `AL`, `GAL`, `H`, `MULTI`, `SPEED`,
+ * `STEEL`, `VA`, `Z` — and mean different products by them: a `Z`-geometry
+ * former is InnoForm, not the `Rekord B-Z Taps` the `FG01` table would name it.
+ * Borrowing that table would put a cutting tap's product line on a forming tap,
+ * which is the one error this category split exists to make impossible. So the
+ * codes pass through verbatim, which is what the paragraph above already says a
+ * code with no article page does, and naming them from the vendor's own
+ * cold-forming pages is the follow-up.
  */
 export const PRODUCT_LINES = {
     // `/us/en/multi-drill/a/MultiDRILL`, `/us/en/steeldrill/a/SteelDrill`,
@@ -527,6 +538,7 @@ export function tapRecord(row, family, columns, options = {}) {
         ...common(row, family, what, warn),
         kind: 'tap',
         unit,
+        threadMethod: fact(family, 'threadMethod', family.threadMethod),
         geometry: {
             DC: required(row, columns, 'DC', unit, what, opts),
             TP: required(row, columns, 'TP', unit, what, opts),

package/dist/vendors/kennametal/catalog.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The category walk — what Kennametal publishes under a facet, family by family.
+ *
+ * `scrape.ts` fetches a family once its **code** is known, and until now the
+ * only way to learn a code was to open a category page in a browser and read it
+ * out of a link. That is why `families/kennametal.ts` carried collet families
+ * with no `familyCode` at all: nobody had written the codes down, because there
+ * was nothing to write them down from.
+ *
+ * **Nothing in a scrape uses this.** `families/kennametal.ts` names every family
+ * in scope and a scrape fetches exactly those; re-deriving the list at scrape
+ * time would put a crawl in front of every run to rediscover something already
+ * recorded. It is here for the maintenance question that table cannot answer —
+ * *has Kennametal added, split or retired a family?* — and the CLI exposes it as
+ * `kennametal --collets`, which reconciles the walk against the recorded codes.
+ *
+ * ## The endpoint, and how it was found
+ *
+ * A category page renders its results client-side, so the HTML a browser is
+ * served carries facet chrome and no products. The component behind it is a
+ * plain AEM GET, read out of the page's own `product-listing.min.js`:
+ *
+ * ```js
+ * url: a + "." + c + ".html?" + h + "query=" + d + "&sort=" + e + "&pageSize=" + f
+ * ```
+ *
+ * where `a` is the component path, `c` is a **page index** and `d` is the same
+ * facet string the browser's address bar carries. Three things about it cost
+ * time to find and are recorded in `docs/KENNAMETAL_PRODUCT_LISTING.md`:
+ *
+ * - The public `/us/en/...` path works. The authoring `/content/kennametal/...`
+ *   path the markup's own `data-path` shows answers 307.
+ * - A non-numeric selector (`.results.`, `.products.`) returns the site's 404
+ *   page **with a 404 status**, so a wrong guess fails rather than parsing to
+ *   nothing.
+ * - `pageSize` counts **families**, not parts. At `pageSize=2` the seven-family
+ *   coolant-through leaf pages two at a time, which is why {@link colletListingPages}
+ *   pages at all rather than asking once and trusting it.
+ *
+ * ## The tree is two shapes, not one
+ *
+ * A category above the leaves returns **category tiles** — facet links, each
+ * extending its parent's query by one `allCategoriesKMT` id — and no families.
+ * A leaf returns family links and no tiles. The tap-collet category is a leaf at
+ * depth 0 and the standard-collet one is not, so a walk that assumed either
+ * shape would find half the catalog.
+ */
+import type { Fetcher } from '../../fetch.js';
+import { type AemBrandName } from '../../identity.js';
+import { type Warn } from '../../scrape.js';
+/**
+ * The product-listing component, per category page.
+ *
+ * A different resource from `scrape.BASE`: that one is the variant table on the
+ * shared `products/fam` page, this one hangs off the category's own path. The
+ * component node is `product_listing` on both AEM brands.
+ */
+export declare const LISTING_BASE: string;
+/** Where the collet walk starts: the category path, and the three facet queries. */
+export declare const COLLET_CATEGORY = "metalworking-tools/tool-holders-and-adapters/collets-and-sleeves";
+/**
+ * The three collet lines this package covers, as the vendor's own facets.
+ *
+ * Read off the category listing on 2026-09-08. Each is the query string the
+ * browser's address bar carries for that line, with `obsoleteFacet:false` — the
+ * same active-only scoping `scrape.ACTIVE_ONLY` applies to a family — and the
+ * `allCategoriesKMT` chain that names Collets and Sleeves (`42034262`), ER
+ * Collets (`42866150`) and then the line.
+ *
+ * Kennametal's collet catalog is larger: `42034262` also holds sleeves, DA and
+ * TG collets and shrink sleeves. These are the three lines asked for, and
+ * adding a fourth is a decision rather than a widening of a pattern.
+ */
+export declare const COLLET_CATEGORIES: readonly {
+    readonly name: string;
+    readonly query: string;
+}[];
+/**
+ * How many families a listing page returns.
+ *
+ * Sixty because that is the largest the vendor's own control offers and every
+ * line in scope fits one page at it — so the walk is one request per node in
+ * practice, and still correct if a line outgrows it.
+ */
+export declare const LISTING_PAGE_SIZE = 60;
+/** One family a leaf category links to. */
+export interface FamilyLink {
+    /** The vendor's numeric family code — what `scrapeFamily` takes. */
+    readonly code: string;
+    /** The slug in the same link, which is the vendor's own name for the family. */
+    readonly slug: string;
+}
+/** One subcategory a listing page offers, as a facet rather than a path. */
+export interface CategoryTile {
+    /** The parent's query with one more `allCategoriesKMT` id on the end. */
+    readonly query: string;
+    /** The vendor's own name for it, off the tile's `data-title`. */
+    readonly name: string;
+    /** What the tile's `(117)` said. */
+    readonly count: number;
+}
+/** What one listing response holds. */
+export interface ColletListing {
+    /** `data-totalResults`, or 0 where the response states none. */
+    readonly total: number;
+    readonly tiles: readonly CategoryTile[];
+    readonly families: readonly FamilyLink[];
+}
+/** One page of one category's listing. */
+export declare function listingUrl(query: string, page: number, brand?: AemBrandName, category?: string, size?: number): string;
+/**
+ * One listing response: its tiles, its family links and its stated total.
+ *
+ * The tile's three facts arrive in three places — the query on the anchor, the
+ * count in a `<span class="count">` inside it, the name in a `data-title` on a
+ * `<div>` inside it — so this tracks the open anchor rather than matching a
+ * shape. A page's facet sidebar carries hundreds of other `data-query` anchors;
+ * `horizontal-facet` is the class the tiles alone wear, and it is what
+ * separates a subcategory from a filter checkbox.
+ */
+export declare function parseColletListing(html: string): ColletListing;
+/**
+ * Every page of one collet category, until a page adds no family it had not seen.
+ *
+ * The vendor states no page count anywhere, and `data-totalResults` counts
+ * *parts* while `pageSize` counts *families*, so the two cannot be divided into
+ * a page budget. What ends the walk is the page itself: an index past the last
+ * one returns the facet chrome with no families in it.
+ *
+ * Tiles come from the first page only. A category with subcategories publishes
+ * them on every page and recursing on a duplicate would re-walk the branch.
+ */
+export declare function colletListingPages(fetcher: Fetcher, query: string, options?: {
+    brand?: AemBrandName;
+    category?: string;
+    delayMs?: number;
+}): Promise<ColletListing>;
+/** One node of the walk: the facet that was asked, and what came back. */
+export interface DiscoveredCategory {
+    readonly name: string;
+    readonly query: string;
+    /** `data-totalResults` — how many parts the vendor counts under this facet. */
+    readonly total: number;
+    readonly families: readonly FamilyLink[];
+}
+/**
+ * Every family reachable from `roots`, depth first and paced.
+ *
+ * A tile's query has to **extend** its parent's, which is the same prefix test
+ * `vendors/maritool/catalog.ts` applies to a cPath and for the same reason: a
+ * listing page renders unrelated facets beside its own subcategories, so taking
+ * every `horizontal-facet` anchor would walk out of the branch that was asked
+ * for and into the whole catalog.
+ *
+ * Sequential and paced by the package's shared politeness delay. The three
+ * collet lines reach seven nodes, so this is a handful of requests run by hand.
+ */
+export declare function discoverFamilies(fetcher: Fetcher, roots?: readonly {
+    name: string;
+    query: string;
+}[], options?: {
+    warn?: Warn;
+    brand?: AemBrandName;
+    category?: string;
+    delayMs?: number;
+}): Promise<DiscoveredCategory[]>;
+/** One line per family, for a human reading a `--collets` run. */
+export declare function describeFamily(category: DiscoveredCategory, family: FamilyLink, configured: string | null): string;

package/dist/vendors/kennametal/catalog.js

@@ -0,0 +1,247 @@
+/**
+ * The category walk — what Kennametal publishes under a facet, family by family.
+ *
+ * `scrape.ts` fetches a family once its **code** is known, and until now the
+ * only way to learn a code was to open a category page in a browser and read it
+ * out of a link. That is why `families/kennametal.ts` carried collet families
+ * with no `familyCode` at all: nobody had written the codes down, because there
+ * was nothing to write them down from.
+ *
+ * **Nothing in a scrape uses this.** `families/kennametal.ts` names every family
+ * in scope and a scrape fetches exactly those; re-deriving the list at scrape
+ * time would put a crawl in front of every run to rediscover something already
+ * recorded. It is here for the maintenance question that table cannot answer —
+ * *has Kennametal added, split or retired a family?* — and the CLI exposes it as
+ * `kennametal --collets`, which reconciles the walk against the recorded codes.
+ *
+ * ## The endpoint, and how it was found
+ *
+ * A category page renders its results client-side, so the HTML a browser is
+ * served carries facet chrome and no products. The component behind it is a
+ * plain AEM GET, read out of the page's own `product-listing.min.js`:
+ *
+ * ```js
+ * url: a + "." + c + ".html?" + h + "query=" + d + "&sort=" + e + "&pageSize=" + f
+ * ```
+ *
+ * where `a` is the component path, `c` is a **page index** and `d` is the same
+ * facet string the browser's address bar carries. Three things about it cost
+ * time to find and are recorded in `docs/KENNAMETAL_PRODUCT_LISTING.md`:
+ *
+ * - The public `/us/en/...` path works. The authoring `/content/kennametal/...`
+ *   path the markup's own `data-path` shows answers 307.
+ * - A non-numeric selector (`.results.`, `.products.`) returns the site's 404
+ *   page **with a 404 status**, so a wrong guess fails rather than parsing to
+ *   nothing.
+ * - `pageSize` counts **families**, not parts. At `pageSize=2` the seven-family
+ *   coolant-through leaf pages two at a time, which is why {@link colletListingPages}
+ *   pages at all rather than asking once and trusting it.
+ *
+ * ## The tree is two shapes, not one
+ *
+ * A category above the leaves returns **category tiles** — facet links, each
+ * extending its parent's query by one `allCategoriesKMT` id — and no families.
+ * A leaf returns family links and no tiles. The tap-collet category is a leaf at
+ * depth 0 and the standard-collet one is not, so a walk that assumed either
+ * shape would find half the catalog.
+ */
+import { Parser } from 'htmlparser2';
+import { BRANDS } from '../../identity.js';
+import { compare } from '../../order.js';
+import { consoleWarn, pause, REQUEST_DELAY_MS } from '../../scrape.js';
+/**
+ * The product-listing component, per category page.
+ *
+ * A different resource from `scrape.BASE`: that one is the variant table on the
+ * shared `products/fam` page, this one hangs off the category's own path. The
+ * component node is `product_listing` on both AEM brands.
+ */
+export const LISTING_BASE = 'https://www.{host}/us/en/products/{category}/_jcr_content/root/' +
+    'responsivegrid/product_listing.{page}.html?query={query}&sort=&pageSize={size}';
+/** Where the collet walk starts: the category path, and the three facet queries. */
+export const COLLET_CATEGORY = 'metalworking-tools/tool-holders-and-adapters/collets-and-sleeves';
+/**
+ * The three collet lines this package covers, as the vendor's own facets.
+ *
+ * Read off the category listing on 2026-09-08. Each is the query string the
+ * browser's address bar carries for that line, with `obsoleteFacet:false` — the
+ * same active-only scoping `scrape.ACTIVE_ONLY` applies to a family — and the
+ * `allCategoriesKMT` chain that names Collets and Sleeves (`42034262`), ER
+ * Collets (`42866150`) and then the line.
+ *
+ * Kennametal's collet catalog is larger: `42034262` also holds sleeves, DA and
+ * TG collets and shrink sleeves. These are the three lines asked for, and
+ * adding a fourth is a decision rather than a widening of a pattern.
+ */
+export const COLLET_CATEGORIES = [
+    {
+        name: 'ER Standard Collets',
+        query: ':relevance:obsoleteFacet:false:allCategoriesKMT:42034262' +
+            ':allCategoriesKMT:42866150:allCategoriesKMT:51114268',
+    },
+    {
+        name: 'ER Coolant Through Collets',
+        query: ':relevance:obsoleteFacet:false:allCategoriesKMT:42034262' +
+            ':allCategoriesKMT:42866150:allCategoriesKMT:109337175',
+    },
+    {
+        name: 'ER Tap Collets',
+        query: ':relevance:obsoleteFacet:false:allCategoriesKMT:42034262' +
+            ':allCategoriesKMT:42866150:allCategoriesKMT:109337171',
+    },
+];
+/**
+ * How many families a listing page returns.
+ *
+ * Sixty because that is the largest the vendor's own control offers and every
+ * line in scope fits one page at it — so the walk is one request per node in
+ * practice, and still correct if a line outgrows it.
+ */
+export const LISTING_PAGE_SIZE = 60;
+/** `/us/en/products/fam.er-standard-collets-metric.100000478.html` */
+const FAMILY_HREF = /\/products\/fam\.([A-Za-z0-9-]+)\.(\d+)\.html/;
+/** `data-totalResults="224"` — htmlparser2 lower-cases attribute names. */
+const TOTAL = /data-totalresults="(\d+)"/i;
+/** One page of one category's listing. */
+export function listingUrl(query, page, brand = 'kennametal', category = COLLET_CATEGORY, size = LISTING_PAGE_SIZE) {
+    return LISTING_BASE.replace('{host}', BRANDS[brand].host)
+        .replace('{category}', category)
+        .replace('{page}', String(page))
+        .replace('{query}', encodeURIComponent(query))
+        .replace('{size}', String(size));
+}
+/**
+ * One listing response: its tiles, its family links and its stated total.
+ *
+ * The tile's three facts arrive in three places — the query on the anchor, the
+ * count in a `<span class="count">` inside it, the name in a `data-title` on a
+ * `<div>` inside it — so this tracks the open anchor rather than matching a
+ * shape. A page's facet sidebar carries hundreds of other `data-query` anchors;
+ * `horizontal-facet` is the class the tiles alone wear, and it is what
+ * separates a subcategory from a filter checkbox.
+ */
+export function parseColletListing(html) {
+    const tiles = [];
+    const families = new Map();
+    let open = null;
+    let counting = false;
+    const parser = new Parser({
+        onopentag: (tag, attribs) => {
+            if (tag === 'a') {
+                const href = attribs['href'] ?? '';
+                const found = FAMILY_HREF.exec(href);
+                if (found !== null) {
+                    families.set(found[2], { code: found[2], slug: found[1] });
+                    return;
+                }
+                const cls = attribs['class'] ?? '';
+                const query = attribs['data-query'];
+                if (cls.includes('horizontal-facet') && query !== undefined) {
+                    open = { query, name: '', count: 0 };
+                }
+                return;
+            }
+            if (open === null)
+                return;
+            if (tag === 'span' && (attribs['class'] ?? '').includes('count'))
+                counting = true;
+            const title = attribs['data-title'];
+            if (title !== undefined)
+                open.name = title;
+        },
+        ontext: (text) => {
+            if (!counting)
+                return;
+            const digits = /(\d+)/.exec(text);
+            if (digits !== null)
+                open.count = Number(digits[1]);
+        },
+        onclosetag: (tag) => {
+            if (tag === 'span')
+                counting = false;
+            if (tag === 'a' && open !== null) {
+                tiles.push(open);
+                open = null;
+            }
+        },
+    }, { decodeEntities: true });
+    parser.write(html);
+    parser.end();
+    return {
+        total: Number(TOTAL.exec(html)?.[1] ?? 0),
+        tiles,
+        families: [...families.values()].sort((a, b) => compare(a.code, b.code)),
+    };
+}
+/**
+ * Every page of one collet category, until a page adds no family it had not seen.
+ *
+ * The vendor states no page count anywhere, and `data-totalResults` counts
+ * *parts* while `pageSize` counts *families*, so the two cannot be divided into
+ * a page budget. What ends the walk is the page itself: an index past the last
+ * one returns the facet chrome with no families in it.
+ *
+ * Tiles come from the first page only. A category with subcategories publishes
+ * them on every page and recursing on a duplicate would re-walk the branch.
+ */
+export async function colletListingPages(fetcher, query, options = {}) {
+    const { brand = 'kennametal', category = COLLET_CATEGORY, delayMs = REQUEST_DELAY_MS } = options;
+    const families = new Map();
+    let first = null;
+    for (let page = 0;; page += 1) {
+        if (page > 0)
+            await pause(delayMs);
+        const listing = parseColletListing(await fetcher.text(listingUrl(query, page, brand, category)));
+        first ??= listing;
+        const before = families.size;
+        for (const family of listing.families)
+            families.set(family.code, family);
+        if (families.size === before)
+            break;
+    }
+    return {
+        total: first?.total ?? 0,
+        tiles: first?.tiles ?? [],
+        families: [...families.values()].sort((a, b) => compare(a.code, b.code)),
+    };
+}
+/**
+ * Every family reachable from `roots`, depth first and paced.
+ *
+ * A tile's query has to **extend** its parent's, which is the same prefix test
+ * `vendors/maritool/catalog.ts` applies to a cPath and for the same reason: a
+ * listing page renders unrelated facets beside its own subcategories, so taking
+ * every `horizontal-facet` anchor would walk out of the branch that was asked
+ * for and into the whole catalog.
+ *
+ * Sequential and paced by the package's shared politeness delay. The three
+ * collet lines reach seven nodes, so this is a handful of requests run by hand.
+ */
+export async function discoverFamilies(fetcher, roots = COLLET_CATEGORIES, options = {}) {
+    const { warn = consoleWarn, delayMs = REQUEST_DELAY_MS, ...where } = options;
+    const found = [];
+    const seen = new Set();
+    const walk = async (name, query) => {
+        if (seen.has(query))
+            return;
+        seen.add(query);
+        const listing = await colletListingPages(fetcher, query, { ...where, delayMs });
+        found.push({ name, query, total: listing.total, families: listing.families });
+        const children = listing.tiles.filter((tile) => tile.query.startsWith(`${query}:`));
+        if (children.length === 0 && listing.families.length === 0) {
+            warn(`  WARNING: ${name} holds neither a subcategory nor a family`);
+        }
+        for (const tile of children) {
+            await pause(delayMs);
+            await walk(tile.name, tile.query);
+        }
+    };
+    for (const root of roots)
+        await walk(root.name, root.query);
+    return found;
+}
+/** One line per family, for a human reading a `--collets` run. */
+export function describeFamily(category, family, configured) {
+    const where = configured ?? '(not configured)';
+    return `${family.code}\t${family.slug}\t${category.name}\t${where}`;
+}