@toolpath/tool-scraper 2.0.0 → 2.2.0

package/dist/vendors/kennametal/holding.js

@@ -0,0 +1,112 @@
+/**
+ * Kennametal's and WIDIA's toolholding column vocabulary, and nothing else.
+ *
+ * The counterpart of `records.ts` for a holder and a collet: every decision
+ * about *what a record is* lives in `holding.ts`, and what lives here is which
+ * of this vendor's columns answers each question. That is the same line
+ * `vendors/kennametal/records.ts` draws for cutting tools.
+ *
+ * ## What this platform states as a fact rather than a column
+ *
+ * Almost everything. `taper`, `contact`, `clamping`, `style` and `unit` are all
+ * per-family constants here, declared in `families/kennametal.ts` with a
+ * citation each, because Kennametal sells one interface and one clamping mode
+ * per family — its dual-contact BT30 is a separate line (BTKV\*) with its own
+ * family code. The two vendors whose holders vary row by row are the ones whose
+ * mappers read a column instead.
+ *
+ * ## Two published columns this deliberately does not carry
+ *
+ * - **`L1FC`**, the BTKV30 line's "Gage Length Face Contact", 0.998 mm shorter
+ *   than `L1` on every row. It is not a second measurement of one thing: it is
+ *   the gage length *in a face-contact spindle*, so which of the two is true is
+ *   a fact about the machine rather than about the holder. Carrying both would
+ *   put two numbers named "gage" on one record with nothing to say which one
+ *   stickout arithmetic should use. `contact` records that the holder has the
+ *   geometry; `gaugeLength` stays `L1`. Promote it the day something reads a
+ *   spindle's contact mode, and change `gaugeLength` with it rather than
+ *   showing both.
+ * - **Torque figures, actuation-screw drive size, weight and `D21`.** Published,
+ *   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 { familyBrand } from '../../family.js';
+import { checkUnitAgreement, clampingMode, colletRecord, contactMode, dim, holderRecord, holdingFact, published, } from '../../holding.js';
+import { consoleWarn } from '../../scrape.js';
+import { CATALOG_NUMBER, MATERIAL_NUMBER } from './records.js';
+/**
+ * The dimensional labels whose two unit columns are worth cross-checking.
+ *
+ * Every dimension either record carries, and no more: a label nothing reads
+ * cannot produce a wrong number, so warning about it is noise. `holding.dim`
+ * reads the native column and never the other one, which is what makes this a
+ * report rather than a gate.
+ */
+const HOLDER_LABELS = ['D1', 'L1', 'L2', 'L9', 'V', 'D2', 'D11'];
+const COLLET_LABELS = ['CCCN', 'CCCX', 'D1', 'BDX', 'LF', 'L'];
+/** How a part names itself in a warning or a refusal. */
+function subject(row) {
+    return `${row[CATALOG_NUMBER] ?? ''} (${row[MATERIAL_NUMBER] ?? ''})`;
+}
+/** One Kennametal or WIDIA holder row -> one {@link HolderRecord}. */
+function holder(row, family, options = {}) {
+    const warn = options.warn ?? consoleWarn;
+    const what = subject(row);
+    const unit = holdingFact(family, 'unit', family.unit);
+    for (const label of HOLDER_LABELS)
+        checkUnitAgreement(row, label, what, warn);
+    // Kennametal publishes no description column for toolholding, and `''` is the
+    // honest answer where a vendor publishes none — `records.ToolRecord.description`
+    // states the rule and the reason: a description that restates the catalog
+    // number puts one string in two fields.
+    return holderRecord({
+        brand: familyBrand(family),
+        materialNumber: published(row[MATERIAL_NUMBER], what, 'material number'),
+        catalogNumber: published(row[CATALOG_NUMBER], what, 'catalog number'),
+        description: '',
+        unit,
+        taper: holdingFact(family, 'taper', family.taper),
+        contact: contactMode(holdingFact(family, 'contact', family.contact), what),
+        clamping: clampingMode(holdingFact(family, 'clamping', family.clamping), what),
+        style: holdingFact(family, 'style', family.style),
+        colletSeries: row[COLLET_SERIES_COLUMN] || null,
+        bore: dim(row, 'D1', unit),
+        gaugeLength: published(dim(row, 'L1', unit), what, 'L1 gage length'),
+        usableLength: dim(row, 'L2', unit),
+        clampingLength: dim(row, 'L9', unit),
+        adjustmentRange: dim(row, 'V', unit),
+        bodyDiameter: dim(row, 'D2', unit),
+        lockNutDiameter: dim(row, 'D11', unit),
+        cadModelUrl: row[CAD_COLUMN] || null,
+        // This platform publishes a STEP model and no 2D profile. A DXF column would
+        // be a claim about the data, and false — the call `conventions.CAD_DXF_COLUMN`
+        // records.
+        cadDxfUrl: null,
+    });
+}
+/** One Kennametal or WIDIA collet row -> one {@link ColletRecord}. */
+function collet(row, family, options = {}) {
+    const warn = options.warn ?? consoleWarn;
+    const what = subject(row);
+    const unit = holdingFact(family, 'unit', family.unit);
+    for (const label of COLLET_LABELS)
+        checkUnitAgreement(row, label, what, warn);
+    return colletRecord({
+        brand: familyBrand(family),
+        materialNumber: published(row[MATERIAL_NUMBER], what, 'material number'),
+        catalogNumber: published(row[CATALOG_NUMBER], what, 'catalog number'),
+        description: '',
+        unit,
+        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'),
+        bodyDiameter: dim(row, 'BDX', unit),
+        functionalLength: dim(row, 'LF', unit),
+        overallLength: dim(row, 'L', unit),
+    });
+}
+/** The toolholding half of the adapter contract `registry` looks up by brand. */
+export const HOLDING_MAPPERS = { holder, collet };

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

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

package/dist/vendors/kennametal/index.js

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

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

@@ -52,6 +52,22 @@ export declare const CATALOG_NUMBER = "ISO Catalog Number";
  * absent coating column is a table that states no coating, not a scrape fault.
  */
 export declare const COATING = "Coating";
+/**
+ * The column {@link productLine} reads, and the one this adapter names rather
+ * than the vendor.
+ *
+ * `conventions.FAMILY_TITLE_COLUMN` is vendor-neutral because a second vendor
+ * publishing a family title should write the same column; this one is not,
+ * because it holds a *segment* of that title that this adapter chose to split
+ * out. A vendor whose product line arrives some other way has no business
+ * writing here — EMUGE reads its own `product line` and `Geometry` columns and
+ * never sees this one.
+ *
+ * Both columns are written by `scrape.scrapeFamily` under `familyTitle`, and
+ * a CSV scraped before that option existed has neither — which is why
+ * {@link productLine} reads it as absent rather than required.
+ */
+export declare const PRODUCT_LINE_COLUMN = "Product Line";
 /**
  * A drill, in the family's native unit system per its `unit` fact.
  *

package/dist/vendors/kennametal/records.js

@@ -55,6 +55,35 @@ export const CATALOG_NUMBER = 'ISO Catalog Number';
  * absent coating column is a table that states no coating, not a scrape fault.
  */
 export const COATING = 'Coating';
+/**
+ * The column {@link productLine} reads, and the one this adapter names rather
+ * than the vendor.
+ *
+ * `conventions.FAMILY_TITLE_COLUMN` is vendor-neutral because a second vendor
+ * publishing a family title should write the same column; this one is not,
+ * because it holds a *segment* of that title that this adapter chose to split
+ * out. A vendor whose product line arrives some other way has no business
+ * writing here — EMUGE reads its own `product line` and `Geometry` columns and
+ * never sees this one.
+ *
+ * Both columns are written by `scrape.scrapeFamily` under `familyTitle`, and
+ * a CSV scraped before that option existed has neither — which is why
+ * {@link productLine} reads it as absent rather than required.
+ */
+export const PRODUCT_LINE_COLUMN = 'Product Line';
+/**
+ * The vendor's own product line for this row, or null where the CSV has none.
+ *
+ * **An absent column is not a fault.** It is a table scraped without
+ * `scrape.FamilyOptions.familyTitle`, or a family page the vendor publishes
+ * with no heading, and both are rows that are otherwise complete. `null` is
+ * the answer `records.ToolRecord.productLine` defines for exactly this — see
+ * its docstring on why that is not `''`.
+ */
+function productLine(row) {
+    const stated = (row[PRODUCT_LINE_COLUMN] ?? '').trim();
+    return stated === '' ? null : stated;
+}
 /**
  * One canonical dimension, or null when this family maps or publishes none.
  *
@@ -160,6 +189,7 @@ export function drillRecord(row, family, columns) {
         vendor: BRANDS[familyBrand(family)].vendor,
         materialNumber: what,
         catalogNumber: row[CATALOG_NUMBER] ?? '',
+        productLine: productLine(row),
         // Kennametal publishes no description column on any table. The catalog
         // number is already on the record, and repeating it here said nothing —
         // see `records.ToolRecord.description`.
@@ -210,6 +240,7 @@ export function tapRecord(row, family, columns) {
         // carry the size. The catalog number no longer leads it — it is already on
         // the record, and a description that restates one is not a description.
         description: tdz,
+        productLine: productLine(row),
         kind: 'tap',
         unit,
         substrate: fact(family, 'bmc', family.bmc),
@@ -251,6 +282,7 @@ export function endmillRecord(row, family, columns) {
         catalogNumber: row[CATALOG_NUMBER] ?? '',
         // No description column here either. See the drill mapper.
         description: '',
+        productLine: productLine(row),
         kind: 'endmill',
         unit,
         substrate: fact(family, 'bmc', family.bmc),

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

@@ -25,7 +25,7 @@
  */
 import type { Fetcher } from '../../fetch.js';
 import { type AemBrandName } from '../../identity.js';
-import type { ScrapeResult } from '../../scrape.js';
+import { type ScrapeResult } from '../../scrape.js';
 export declare const BASE: string;
 /**
  * The Hybris/Solr facet string that scopes a request to a family's active
@@ -101,11 +101,34 @@ export declare function parseVariantTable(html: string): VariantTable;
  * data row.
  */
 export declare function columnNames(header: readonly Cell[]): (string | null)[];
+/** What {@link scrapeFamily} accepts beyond its tags. */
+export interface FamilyOptions {
+    /**
+     * Also read the family page's own title, and tag every row with it.
+     *
+     * **Opt-in, and a second request.** The variants table states no product
+     * line — the vendor puts it in the `h1` above the table, which is a
+     * different AEM resource — so this is the one thing here that costs a
+     * request the table did not. A caller that only wants dimensions should not
+     * pay for it, and every existing caller keeps the transport it had.
+     *
+     * See `family.ts` for what the title is and which part of it becomes
+     * `records.ToolRecord.productLine`.
+     */
+    readonly familyTitle?: boolean;
+    /** Milliseconds between the two requests. Zero in tests. */
+    readonly delayMs?: number;
+}
 /**
  * Scrape one family into rows.
  *
  * `tags` is a sequence of `[name, value]` pairs appended to every row as
  * constant columns — used to tag facts the table doesn't state, e.g. the
  * thread system on a tap family.
+ *
+ * `options.familyTitle` adds two more of exactly that kind. They are tags
+ * rather than parsed columns because that is what they are: one string per
+ * family, constant down its whole table, which is the case the `tags` seam was
+ * built for.
  */
-export declare function scrapeFamily(fetcher: Fetcher, code: string, brand?: AemBrandName, tags?: readonly Tag[]): Promise<ScrapeResult>;
+export declare function scrapeFamily(fetcher: Fetcher, code: string, brand?: AemBrandName, tags?: readonly Tag[], options?: FamilyOptions): Promise<ScrapeResult>;

package/dist/vendors/kennametal/scrape.js

@@ -24,8 +24,12 @@
  * characters.
  */
 import { Parser } from 'htmlparser2';
+import { FAMILY_TITLE_COLUMN } from '../../conventions.js';
 import { VendorResponseError } from '../../errors.js';
 import { BRANDS } from '../../identity.js';
+import { pause, REQUEST_DELAY_MS } from '../../scrape.js';
+import { fetchFamily } from './family.js';
+import { PRODUCT_LINE_COLUMN } from './records.js';
 export const BASE = 'https://www.{host}/us/en/products/fam/_jcr_content/root/' +
     'responsivegrid/{node}.variants.{code}.html' +
     '?query={query}&uom=metric';
@@ -194,16 +198,37 @@ export function columnNames(header) {
  * `tags` is a sequence of `[name, value]` pairs appended to every row as
  * constant columns — used to tag facts the table doesn't state, e.g. the
  * thread system on a tap family.
+ *
+ * `options.familyTitle` adds two more of exactly that kind. They are tags
+ * rather than parsed columns because that is what they are: one string per
+ * family, constant down its whole table, which is the case the `tags` seam was
+ * built for.
  */
-export async function scrapeFamily(fetcher, code, brand = 'kennametal', tags = []) {
+export async function scrapeFamily(fetcher, code, brand = 'kennametal', tags = [], options = {}) {
     const url = variantsUrl(code, brand);
     const { header, rows: dataRows } = parseVariantTable(await fetcher.text(url));
     if (header === null) {
         throw new VendorResponseError(`family ${code}`, 'the vendor returned no variants');
     }
+    // After the table, so a family the vendor no longer publishes fails on the
+    // table it has no rows for rather than on a title nobody would have read.
+    const titled = [];
+    if (options.familyTitle === true) {
+        await pause(options.delayMs ?? REQUEST_DELAY_MS);
+        const { title, productLine } = await fetchFamily(fetcher, code, brand);
+        // A page with no heading writes no columns, rather than a column of empty
+        // strings that reads as a vendor stating an empty name. `unionHeader` is
+        // not in play here — this header is positional — so an absent tag is
+        // simply a narrower CSV.
+        if (title !== '')
+            titled.push([FAMILY_TITLE_COLUMN, title]);
+        if (productLine !== null)
+            titled.push([PRODUCT_LINE_COLUMN, productLine]);
+    }
     const names = columnNames(header);
     const kept = names.filter((name) => name !== null);
-    const csvHeader = [...kept, ...tags.map(([name]) => name)];
+    const allTags = [...tags, ...titled];
+    const csvHeader = [...kept, ...allTags.map(([name]) => name)];
     const rows = dataRows.map((row) => {
         // `dataRows` is filtered to rows exactly as long as the header, and
         // `names` has one entry per header cell, so a length mismatch here means
@@ -218,7 +243,7 @@ export async function scrapeFamily(fetcher, code, brand = 'kennametal', tags = [
             if (name !== null)
                 out[name] = row[index]?.[0] ?? '';
         });
-        for (const [name, value] of tags)
+        for (const [name, value] of allTags)
             out[name] = value;
         return out;
     });

package/dist/vendors/maritool/holding.d.ts

@@ -0,0 +1,79 @@
+/**
+ * MariTool's toolholding column vocabulary, and nothing else.
+ *
+ * The vendor at the far end of the range this package covers: where Kennametal
+ * states a holder's taper, contact, clamping mode, style and unit as five
+ * per-family constants, MariTool states every one of them per part.
+ * `families/maritool.ts` declares **no facts at all** for exactly that reason —
+ * each CSV is one spindle taper holding three clamping styles, the HSK file
+ * holds nine sizes, and `Gage Length` is metric on some parts and imperial on
+ * others inside one category page. So this mapper reads columns where the
+ * Kennametal one reads facts, and the record shape is the same either way.
+ *
+ * ## The record's unit comes from the gage length
+ *
+ * `scrape.holderRow` promotes `Gage Length` into the `conventions.GAGE_COLUMNS`
+ * pair with **exactly one cell filled**, and which one is filled is the only
+ * statement about unit system this vendor makes per part. That is what
+ * {@link HOLDING_MAPPERS} reads, and a row with both cells filled is refused
+ * rather than resolved: it would mean the scraper had changed shape, and
+ * picking one would hide that.
+ *
+ * ## `Shank Size` is the bore, and a bare cell is inches
+ *
+ * MariTool publishes no `D1`. Its shrink-fit and hydraulic holders state the
+ * shank they take under the vendor's own `Shank Size` label, which
+ * `scrape.holderRow` carries verbatim and unsuffixed — the adapter deliberately
+ * does not promote it, because a promoted column carries a unit suffix and
+ * these families declare no unit for one to be taken from.
+ *
+ * The cell takes three shapes across the 293 non-collet holders in the catalog,
+ * and {@link parseShankSize} reads all three: `.500`, `10mm`, and
+ * `.1181 (3mm)` — a decimal inch with the vendor's own metric annotation beside
+ * it. **A cell that names no unit is inches**, which is a claim about this
+ * vendor and worth the evidence: every bare value published is a fractional
+ * inch size (`.125`, `.1875`, `.250`, `.3125`, `.375`, `.4375`, `.500`, `.625`,
+ * `.750`, `1.0`, `1.25`, `1.5`), and the annotated form proves the reading —
+ * `.1181` is 3 mm in inches, to four places. One part in the catalog states a
+ * bare inch shank on a holder gaged in millimetres (`HSK40E-SF.125-45`), which
+ * is converted rather than warned about: the record's unit is itself promoted
+ * off another cell here, so the two disagreeing is this vendor's shape rather
+ * than a fault.
+ *
+ * ## Two published columns this does not carry
+ *
+ * - **`Nose Diameter`**, on 200-odd parts. It measures the holder's nose and
+ *   `bodyDiameter` is `D2`, the body — promoting one into a field named for the
+ *   other is precisely the collision `conventions` warns about at length. It
+ *   also mixes `.870` with `.870 inches` in one column, which is a second
+ *   reason to leave it as the receipt of what the vendor said.
+ * - **`Collet Grip Range`.** `scrape.holderRow` says why: it is the ER series'
+ *   range restated on the holder's page, a pure function of `Collet Size`, and
+ *   a real capacity comes from a collet family joined on `CST`.
+ */
+import { type UnitSystem } from '../../conventions.js';
+import { type HoldingMappers } from '../../holding.js';
+/** MariTool's own label for the cell {@link parseShankSize} reads a bore from. */
+export declare const SHANK_SIZE_LABEL = "Shank Size";
+/**
+ * MariTool's own label for the lock-nut diameter — `D11`, on five parts.
+ *
+ * Carried where `Nose Diameter` is not, because this one names exactly what the
+ * record's field names: the outside diameter of the collet nut, which is what
+ * decides whether a holder clears a fixture.
+ */
+export declare const COLLET_NUT_DIAMETER_LABEL = "Collet Nut Outside Diameter";
+/** One cell as a diameter and the system it is stated in. Null where unreadable. */
+export declare function parseShankSize(cell: string): {
+    value: number;
+    stated: UnitSystem;
+} | null;
+/**
+ * The toolholding half of the adapter contract `registry` looks up by brand.
+ *
+ * Holders only: MariTool sells collets and this package does not scrape them,
+ * so there is no `collet` mapper and `registry.toHolding` refuses a request for
+ * one naming what this brand does map. A partial table is the honest state for
+ * a kind nobody has read the columns of.
+ */
+export declare const HOLDING_MAPPERS: HoldingMappers;

package/dist/vendors/maritool/holding.js

@@ -0,0 +1,164 @@
+/**
+ * MariTool's toolholding column vocabulary, and nothing else.
+ *
+ * The vendor at the far end of the range this package covers: where Kennametal
+ * states a holder's taper, contact, clamping mode, style and unit as five
+ * per-family constants, MariTool states every one of them per part.
+ * `families/maritool.ts` declares **no facts at all** for exactly that reason —
+ * each CSV is one spindle taper holding three clamping styles, the HSK file
+ * holds nine sizes, and `Gage Length` is metric on some parts and imperial on
+ * others inside one category page. So this mapper reads columns where the
+ * Kennametal one reads facts, and the record shape is the same either way.
+ *
+ * ## The record's unit comes from the gage length
+ *
+ * `scrape.holderRow` promotes `Gage Length` into the `conventions.GAGE_COLUMNS`
+ * pair with **exactly one cell filled**, and which one is filled is the only
+ * statement about unit system this vendor makes per part. That is what
+ * {@link HOLDING_MAPPERS} reads, and a row with both cells filled is refused
+ * rather than resolved: it would mean the scraper had changed shape, and
+ * picking one would hide that.
+ *
+ * ## `Shank Size` is the bore, and a bare cell is inches
+ *
+ * MariTool publishes no `D1`. Its shrink-fit and hydraulic holders state the
+ * shank they take under the vendor's own `Shank Size` label, which
+ * `scrape.holderRow` carries verbatim and unsuffixed — the adapter deliberately
+ * does not promote it, because a promoted column carries a unit suffix and
+ * these families declare no unit for one to be taken from.
+ *
+ * The cell takes three shapes across the 293 non-collet holders in the catalog,
+ * and {@link parseShankSize} reads all three: `.500`, `10mm`, and
+ * `.1181 (3mm)` — a decimal inch with the vendor's own metric annotation beside
+ * it. **A cell that names no unit is inches**, which is a claim about this
+ * vendor and worth the evidence: every bare value published is a fractional
+ * inch size (`.125`, `.1875`, `.250`, `.3125`, `.375`, `.4375`, `.500`, `.625`,
+ * `.750`, `1.0`, `1.25`, `1.5`), and the annotated form proves the reading —
+ * `.1181` is 3 mm in inches, to four places. One part in the catalog states a
+ * bare inch shank on a holder gaged in millimetres (`HSK40E-SF.125-45`), which
+ * is converted rather than warned about: the record's unit is itself promoted
+ * off another cell here, so the two disagreeing is this vendor's shape rather
+ * than a fault.
+ *
+ * ## Two published columns this does not carry
+ *
+ * - **`Nose Diameter`**, on 200-odd parts. It measures the holder's nose and
+ *   `bodyDiameter` is `D2`, the body — promoting one into a field named for the
+ *   other is precisely the collision `conventions` warns about at length. It
+ *   also mixes `.870` with `.870 inches` in one column, which is a second
+ *   reason to leave it as the receipt of what the vendor said.
+ * - **`Collet Grip Range`.** `scrape.holderRow` says why: it is the ER series'
+ *   range restated on the holder's page, a pure function of `Collet Size`, and
+ *   a real capacity comes from a collet family joined on `CST`.
+ */
+import { CAD_COLUMN, CAD_DXF_COLUMN, COLLET_SERIES_COLUMN, CONTACT_COLUMN, DESCRIPTION_COLUMN, GAGE_COLUMNS, } from '../../conventions.js';
+import { IncompletePartError, VendorResponseError } from '../../errors.js';
+import { familyBrand } from '../../family.js';
+import { asUnit, clampingMode, contactMode, holderRecord, published, } from '../../holding.js';
+import { fractionValue } from '../../measure.js';
+import { CLAMPING_COLUMN, MATERIAL_COLUMN, STYLE_COLUMN, TAPER_COLUMN } from './scrape.js';
+/** MariTool's own label for the cell {@link parseShankSize} reads a bore from. */
+export const SHANK_SIZE_LABEL = 'Shank Size';
+/**
+ * MariTool's own label for the lock-nut diameter — `D11`, on five parts.
+ *
+ * Carried where `Nose Diameter` is not, because this one names exactly what the
+ * record's field names: the outside diameter of the collet nut, which is what
+ * decides whether a holder clears a fixture.
+ */
+export const COLLET_NUT_DIAMETER_LABEL = 'Collet Nut Outside Diameter';
+/**
+ * A `Shank Size` cell: a decimal, an optional unit, an optional annotation.
+ *
+ * The annotation is captured only so it can be dropped — it is the vendor's own
+ * conversion of the same dimension (`.1181 (3mm)`), not a second measurement,
+ * and reading it would put two sizes on one holder.
+ *
+ * `inches` leads the unit alternation because a regex alternation is ordered and
+ * `in` would otherwise match the first two letters of `inches` and leave `ches`
+ * unmatched — the same trap `parseGageLength` documents.
+ */
+const SHANK_SIZE = /^(?<value>\d*\.?\d+)\s*(?<unit>mm|inches|inch|in)?\s*(?:\([^)]*\))?$/i;
+/** One cell as a diameter and the system it is stated in. Null where unreadable. */
+export function parseShankSize(cell) {
+    const parsed = SHANK_SIZE.exec(cell.trim())?.groups;
+    if (parsed === undefined)
+        return null;
+    const value = fractionValue(parsed['value'] ?? '');
+    if (value === null || value <= 0)
+        return null;
+    const unit = (parsed['unit'] ?? '').toLowerCase();
+    return { value, stated: unit === 'mm' ? 'millimeters' : 'inches' };
+}
+/** How a part names itself in a warning or a refusal. */
+function subject(row) {
+    return `${row[MATERIAL_COLUMN] ?? ''} (${row[DESCRIPTION_COLUMN] ?? ''})`;
+}
+/** The gage length and, with it, the unit system this record is in. */
+function gage(row, what) {
+    const inches = fractionValue(row[GAGE_COLUMNS.inches] ?? '');
+    const millimeters = fractionValue(row[GAGE_COLUMNS.millimeters] ?? '');
+    if (inches !== null && millimeters !== null) {
+        throw new VendorResponseError(what, `publishes a gage length in both unit columns (${inches} in and ` +
+            `${millimeters} mm) — the scrape fills exactly one, and which one is ` +
+            `filled is the only unit system this vendor states per part`);
+    }
+    if (inches !== null)
+        return { unit: 'inches', gaugeLength: inches };
+    if (millimeters !== null)
+        return { unit: 'millimeters', gaugeLength: millimeters };
+    throw new IncompletePartError(what, 'publishes no gage length in either unit column');
+}
+/** One of MariTool's own unsuffixed diameter cells, in `unit`. */
+function diameter(row, label, unit, what) {
+    const cell = (row[label] ?? '').trim();
+    if (cell === '')
+        return null;
+    const measured = parseShankSize(cell);
+    if (measured === null) {
+        throw new VendorResponseError(what, `${label} is ${JSON.stringify(cell)}, which is not a diameter this ` +
+            `package can read — add its shape to SHANK_SIZE once it is clear what ` +
+            `the vendor means by it`);
+    }
+    return asUnit(measured.value, measured.stated, unit);
+}
+/** One MariTool holder row -> one {@link HolderRecord}. */
+function holder(row, family) {
+    const what = subject(row);
+    const { unit, gaugeLength } = gage(row, what);
+    const material = published(row[MATERIAL_COLUMN], what, 'part number');
+    return holderRecord({
+        brand: familyBrand(family),
+        materialNumber: material,
+        // MariTool publishes one number per part and no second catalog designation
+        // — `conventions.IDENTITY_DEVIATIONS` records why, and inventing one here
+        // would put a column in the record the vendor does not publish. The part
+        // number is what a human orders by, so it is both.
+        catalogNumber: material,
+        description: row[DESCRIPTION_COLUMN] ?? '',
+        unit,
+        // One part in the catalog, `BT40-ER32-60`, publishes no `Taper` cell at all,
+        // and `scrape.holderRow` leaves both columns empty rather than inferring one
+        // from the part number. It becomes no record and a warning, which is the
+        // same call a cutting tool with no overall length gets.
+        taper: published(row[TAPER_COLUMN], what, 'taper'),
+        contact: contactMode(published(row[CONTACT_COLUMN], what, 'contact mode'), what),
+        clamping: clampingMode(published(row[CLAMPING_COLUMN], what, 'clamping mode'), what),
+        style: published(row[STYLE_COLUMN], what, 'style'),
+        colletSeries: row[COLLET_SERIES_COLUMN] || null,
+        bore: diameter(row, SHANK_SIZE_LABEL, unit, what),
+        gaugeLength,
+        lockNutDiameter: diameter(row, COLLET_NUT_DIAMETER_LABEL, unit, what),
+        cadModelUrl: row[CAD_COLUMN] || null,
+        cadDxfUrl: row[CAD_DXF_COLUMN] || null,
+    });
+}
+/**
+ * The toolholding half of the adapter contract `registry` looks up by brand.
+ *
+ * Holders only: MariTool sells collets and this package does not scrape them,
+ * so there is no `collet` mapper and `registry.toHolding` refuses a request for
+ * one naming what this brand does map. A partial table is the honest state for
+ * a kind nobody has read the columns of.
+ */
+export const HOLDING_MAPPERS = { holder };

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

@@ -7,4 +7,5 @@
  * `docs/MARITOOL_CATALOG.md`.
  */
 export * from './catalog.js';
+export * from './holding.js';
 export * from './scrape.js';

package/dist/vendors/maritool/index.js

@@ -7,4 +7,5 @@
  * `docs/MARITOOL_CATALOG.md`.
  */
 export * from './catalog.js';
+export * from './holding.js';
 export * from './scrape.js';

package/dist/vendors/maritool/scrape.d.ts

@@ -26,11 +26,16 @@
  *
  * ## What the vendor gets wrong
  *
- * Four faults found on 2026-08-29, all reported as warnings rather than
+ * Four faults found on 2026-08-29. Three are reported as warnings rather than
  * fixed — two disagreeing vendor cells cannot say which one is wrong, and a
  * scraper that corrects one becomes a place tool data is authored by hand.
  * This is the same call `vendors/regofix/scrape.ts` made on its three.
  *
+ * The fourth is resolved rather than reported, and the difference is where the
+ * answer came from: `docs/ADDING-A-VENDOR.md` says that when a vendor label is
+ * unclear you **ask**, and record the answer and its date. That is what
+ * happened — see fault 2.
+ *
  * 1. **`BT40-ER32-60` publishes no `Taper` row at all**, alone among the 529
  *    parts in scope. Its row is kept with `taper` and `contact` empty rather
  *    than dropped or filled in from its part number: the CSV is a receipt, and
@@ -38,10 +43,21 @@
  * 2. **`Collet Size` carries a collet *nut* designation on two parts.**
  *    `CAT40-ER25-3.0MD` and `BT30-ER25-60M` both state `ER25M`, and `ER25M` is
  *    not a collet series — `HSK40E-ER16-3.0M` puts exactly that shape of value
- *    in its own `Collet Nut` cell, which is the column it belongs in. The
- *    string is written into `CST` as designated, so it joins to no collet
- *    family, and it is warned about. Widening it to `ER25` would offer a
- *    machinist a collet that may not seat.
+ *    in its own `Collet Nut` cell, which is the column it belongs in.
+ *
+ *    **`ER25M` is the mini collet nut series, and the collet it closes is a
+ *    plain ER25** (JG 2026-09-02). So {@link colletSeries} resolves the cell to
+ *    the collet the holder actually takes, and the two parts join to the ER25
+ *    collets they fit. Until that answer existed the string was written through
+ *    as designated and warned about, because widening a series on a guess is
+ *    how a machinist is offered a collet that does not seat — and the cost of
+ *    being wrong the other way was one option, not a purchase.
+ *
+ *    **Nothing is lost by resolving it.** `Collet Size` is one of the vendor's
+ *    own labels and is carried into the CSV verbatim, so the receipt still says
+ *    `ER25M` and still says which of the two parts has a mini nut. What changes
+ *    is only `CST`, which is a derived join key rather than a record of what the
+ *    vendor published — the same thing the spacing rule below does to it.
  * 3. **`Collet Size` is spaced inconsistently within one style** — `ER 11`
  *    and `ER11` are both published. {@link colletSeries} closes the space,
  *    because `CST` is a join key and two spellings of one series join to
@@ -254,15 +270,23 @@ export declare function parseGageLength(cell: string): GageLength;
 /**
  * A `Collet Size` cell as the series `CST` joins a collet family on.
  *
- * Only the spacing is closed. MariTool publishes `ER 11` and `ER11` within one
- * style, and two spellings of one series join to nothing — `CST` is the key
- * `families/kennametal.ts` states the holder-to-collet join against, and the
- * collet side of it spells the series without a space.
+ * **Derived, not a receipt.** `CST` is the key `families/kennametal.ts` states
+ * the holder-to-collet join against, so what belongs in it is the series of the
+ * collet the holder takes. The vendor's own cell is carried into the CSV under
+ * its own label and untouched, which is where the two normalisations below are
+ * still visible.
+ *
+ * Two things are closed, and both exist because two spellings of one series
+ * join to nothing:
+ *
+ * - **Spacing.** MariTool publishes `ER 11` and `ER11` within one style, and
+ *   the collet side of the join spells the series without a space.
+ * - **A nut designation.** `ER25M` names a mini nut, not a collet series — see
+ *   {@link NUT_DESIGNATION} and this module's docstring.
  *
- * Nothing else is normalised. `ER25M` is written through as designated even
- * though no such collet series exists, because the alternative is to decide on
- * the vendor's behalf that its `M` is the mini nut its `Collet Nut` column
- * carries elsewhere — see this module's docstring. {@link holderRow} warns.
+ * Nothing else is. A cell this leaves as neither `ER<n>` nor a nut designation
+ * is written through as the vendor designated it, and {@link holderRow} warns
+ * that it joins to no collet.
  */
 export declare function colletSeries(cell: string): string;
 /**