@toolpath/tool-scraper 2.4.0 → 2.5.0

package/dist/holding.js

@@ -163,6 +163,29 @@ function halfUlp(raw) {
     const fraction = raw.includes('.') ? raw.slice(raw.indexOf('.') + 1) : '';
     return 0.5 * 10 ** -fraction.length;
 }
+/**
+ * How far a collet's *designation* may sit from its measured capacity, as a
+ * fraction of that capacity.
+ *
+ * {@link ColletRecord.nominal} is the size the vendor **designates** the collet
+ * by; {@link ColletRecord.clampMin}/{@link ColletRecord.clampMax} is what it
+ * measures. They are not two readings of one number, and on a sealed collet
+ * they are routinely different: Kennametal's `40ERSS1000` is designated 1 inch
+ * and clamps 0.9938, `40ERSS0500` is designated 1/2 and clamps 0.4943. Both
+ * unit columns agree on both figures — 25.4 against 25.243 mm, 12.7 against
+ * 12.556 — so this is the vendor stating an undersized capacity for a collet it
+ * names by the fraction, not a cell in the wrong column.
+ *
+ * **Relative rather than absolute, because the gap scales with the collet.**
+ * Across the 443-part collet corpus fourteen rows sit outside their own band.
+ * The widest is `40ERSS0812` at 0.193 mm, which is 0.94 % of its 20.4 mm
+ * capacity; the widest by fraction is `40ERSS0500` at 1.14 %. The error this
+ * must still refuse is a cell in the wrong unit system, which is 96 % out — the
+ * shape `16ERSS0312` has, where `D1`'s metric cell holds the inch value. This
+ * sits 4.4x above the first and 19x below the second. A row that lands in
+ * between is a finding to investigate rather than a number to widen.
+ */
+export const NOMINAL_SLACK = 0.05;
 /**
  * Report where a vendor's own millimetre and inch cells disagree.
  *
@@ -298,11 +321,25 @@ export function checkCollet(record) {
     // In the native unit, which is the gate with teeth: these are the values a
     // consumer compares, and the contradictory cells this catalog knows about all
     // sit in the column `dim` ignores.
+    //
+    // The slack is {@link NOMINAL_SLACK}, because a designation is not a
+    // measurement — see that constant for the fourteen rows it exists for and the
+    // margin either side of it. Unit-free, so it needs no conversion.
     if (record.nominal !== null &&
-        (record.nominal < record.clampMin || record.nominal > record.clampMax)) {
+        (record.nominal < record.clampMin * (1 - NOMINAL_SLACK) ||
+            record.nominal > record.clampMax * (1 + NOMINAL_SLACK))) {
         throw new VendorResponseError(what, `nominal ${record.nominal} is outside its own capacity ` +
             `${record.clampMin}-${record.clampMax}`);
     }
+    // A tap's square across flats is inscribed in its shank, so it is smaller
+    // than the bore that takes it — true on all 96 rows of both Kennametal tap
+    // families. A square at or past the clamping diameter is the inch cell in the
+    // metric column or two labels swapped, which is the failure `dim`'s native
+    // read cannot see and `checkUnitAgreement` only reports.
+    if (record.squareSize !== null && record.squareSize >= record.clampMax) {
+        throw new VendorResponseError(what, `square size ${record.squareSize} is not smaller than the ` +
+            `${record.clampMax} it clamps — a square is inscribed in the shank`);
+    }
 }
 /**
  * Build a {@link HolderRecord}: mint its guid, derive its millimetre twins, and
@@ -354,6 +391,10 @@ export function colletRecord(fields) {
         bodyDiameter: fields.bodyDiameter ?? null,
         functionalLength: fields.functionalLength ?? null,
         overallLength: fields.overallLength ?? null,
+        clampingLength: fields.clampingLength ?? null,
+        clampingLengthMm: millimeters(fields.clampingLength ?? null, fields.unit),
+        tapRange: fields.tapRange ?? null,
+        squareSize: fields.squareSize ?? null,
     });
     checkCollet(record);
     return record;

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/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}`;
+}

package/dist/vendors/kennametal/holding.js

@@ -30,7 +30,7 @@
  *   and dropped under `records.ToolRecord`'s standing rule: add a field when
  *   something displays it, not before.
  */
-import { CAD_COLUMN, COLLET_DESIGNATION_COLUMN, COLLET_SERIES_COLUMN } from '../../conventions.js';
+import { CAD_COLUMN, COLLET_DESIGNATION_COLUMN, COLLET_SERIES_COLUMN, dimensionalColumn, } from '../../conventions.js';
 import { familyBrand } from '../../family.js';
 import { checkUnitAgreement, clampingMode, colletRecord, contactMode, dim, holderRecord, holdingFact, published, } from '../../holding.js';
 import { consoleWarn } from '../../scrape.js';
@@ -44,7 +44,19 @@ import { CATALOG_NUMBER, MATERIAL_NUMBER } from './records.js';
  * report rather than a gate.
  */
 const HOLDER_LABELS = ['D1', 'L1', 'L2', 'L9', 'V', 'D2', 'D11'];
-const COLLET_LABELS = ['CCCN', 'CCCX', 'D1', 'BDX', 'LF', 'L'];
+const COLLET_LABELS = ['CCCN', 'CCCX', 'D1', 'BDX', 'LF', 'L', 'L9', 'S10'];
+/**
+ * The square drive a tap collet's bore carries, across flats.
+ *
+ * Kennametal's own label, and it is what tells a tap collet from a round one —
+ * see {@link colletCapacity}. Local to this adapter rather than in
+ * `conventions.ts` for the reason that module states: a column two vendors
+ * write is neutral, and this one is published by Kennametal's tap families and
+ * by nothing else in the catalog.
+ */
+const SQUARE_LABEL = 'S10';
+/** The vendor's own designation of the taps a tap collet is for. */
+const TAP_RANGE_LABEL = 'Tap Range';
 /** How a part names itself in a warning or a refusal. */
 function subject(row) {
     return `${row[CATALOG_NUMBER] ?? ''} (${row[MATERIAL_NUMBER] ?? ''})`;
@@ -85,6 +97,34 @@ function holder(row, family, options = {}) {
         cadDxfUrl: null,
     });
 }
+/**
+ * A collet's clamping capacity, from whichever pair of columns the family
+ * publishes.
+ *
+ * The ER collet families state `CCCN`/`CCCX` and that is what is read. **The
+ * tap families state neither**, and they are not incomplete rows: a square-drive
+ * collet holds one exact shank, and `D1` is it — `16ERTC025` publishes 6.477 mm,
+ * which is 0.255 in, the ANSI shank of a 1/4-20 tap. So the honest capacity is a
+ * zero-width band at `D1`, the same shape a sealed coolant-through collet
+ * already carries and `holding.checkCollet` already permits.
+ *
+ * Keyed on the vendor publishing a **square size** rather than on the family's
+ * `style` string: the square is Kennametal saying this part drives a tap, and a
+ * style is this package's config. A tap family that started publishing a real
+ * band would simply be read from it, which is the right answer either way.
+ */
+function colletCapacity(row, what, unit) {
+    const min = dim(row, 'CCCN', unit);
+    const max = dim(row, 'CCCX', unit);
+    if (min !== null || max !== null || dim(row, SQUARE_LABEL, unit) === null) {
+        return {
+            clampMin: published(min, what, 'CCCN clamping minimum'),
+            clampMax: published(max, what, 'CCCX clamping maximum'),
+        };
+    }
+    const exact = published(dim(row, 'D1', unit), what, 'D1 clamping diameter');
+    return { clampMin: exact, clampMax: exact };
+}
 /** One Kennametal or WIDIA collet row -> one {@link ColletRecord}. */
 function collet(row, family, options = {}) {
     const warn = options.warn ?? consoleWarn;
@@ -101,11 +141,17 @@ function collet(row, family, options = {}) {
         series: published(row[COLLET_DESIGNATION_COLUMN], what, 'collet series'),
         style: holdingFact(family, 'style', family.style),
         nominal: dim(row, 'D1', unit),
-        clampMin: published(dim(row, 'CCCN', unit), what, 'CCCN clamping minimum'),
-        clampMax: published(dim(row, 'CCCX', unit), what, 'CCCX clamping maximum'),
+        ...colletCapacity(row, what, unit),
         bodyDiameter: dim(row, 'BDX', unit),
         functionalLength: dim(row, 'LF', unit),
         overallLength: dim(row, 'L', unit),
+        clampingLength: dim(row, 'L9', unit),
+        // Verbatim, in the family's own unit, and never converted: it is two thread
+        // designations rather than a dimension. The metric families print it in the
+        // metric column and the ANSI ones in the inch column, and a row where the
+        // vendor filled neither says nothing rather than the wrong one.
+        tapRange: row[dimensionalColumn(TAP_RANGE_LABEL, unit)] || null,
+        squareSize: dim(row, SQUARE_LABEL, unit),
     });
 }
 /** The toolholding half of the adapter contract `registry` looks up by brand. */

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

@@ -15,6 +15,7 @@
  * code here at all.
  */
 export * from './cad.js';
+export * from './catalog.js';
 export * from './family.js';
 export * from './holding.js';
 export * from './materials.js';

package/dist/vendors/kennametal/index.js

@@ -15,6 +15,7 @@
  * code here at all.
  */
 export * from './cad.js';
+export * from './catalog.js';
 export * from './family.js';
 export * from './holding.js';
 export * from './materials.js';